Table of Contents

            4.2.3 IBIS Group Routines

4.2.3 IBIS Group Routines

The columns of an IBIS file may be placed into well-defined ordered subsets called "groups". There is one built-in set of groups, which are the "format" groups.; for example, a byte-format column automatically belongs to a group called 'BYTE' (the names are case-insensitive), and the ascii-formatted columns are all in a single group called 'ASCII'; there is no 'A16' -style group.

Groups of columns may be manipulated in many ways. They may be used to define an IBIS "record" structure, which allows formatted access to subsets of columns. Alternatively a sequence of groups may be used to organize a file and to locate a columns whose logical column number is not known. In this way columns may be referenced by their group membership, instead of the logical column number.

This is particularly useful for IBIS files which may undergo modification during the process of a single program or procedure. To the IBIS-2 subroutine library, columns maintain their identity even though their format may change, their data location may move, and their order in the column list may change. Placing a column in a group avoids the hazards of assuming column locations and orders in a file.

For example, there may be a group called "IMAGE-1", and another group called "AVERAGE DN", whose columns contain mean brightness values for various images. Using group expressions, described below, a client program is able to determine the column(s) which are in the intersection of these two groups.

An IBIS file can contain three types of groups: FORMATS, UNITS and GROUPS. In addition, the IBIS library allows for the definition of one additional group type, called LOCAL, which may be defined by client programs for its own purposes, without modifying the contents of the IBIS file's property label. LOCAL groups differ from the other group in the fact that, whereas normal groups must begin with an alphanumeric character, LOCAL groups may also begin with a $dollarsign, insuring a host of names which are guaranteed not to have been taken by the other (public) groups.

In several routines documented below, the type parameter may be used to localize the search for a given group within a certain type. This is because the same name may occur in different group types. If the type parameter is 'any', the search will run through the groups in the order: (formats, units, groups, locals) until a match is found. Alternatively, a "full-pathname" may be used for the group. For example, to find a UNIT group called "meters", default the type name and use the group string "unit:meters". Using a full-pathname when type is not 'any' will result an error status.

The preprocessor macros ITYPE_xxx may be used in place of the type literal-strings. IBISGroupNew

count = IBISGroupNew( ibis,type, name, cols, ncols, expr);
count =  ibis_group_new( ibis,type, name, cols, ncols,expr)

ibis		input	integer
type		input	keyword
name		input	string
cols		input	integer array
ncols		input	integer
expr		input	string
count		output	integer

type = { UNIT | GROUP | LOCAL }, default=LOCAL

Create a new group of type type with name name, using either the group expression expr, or if defaulted, use the explicit column list cols. The total number of columns installed in the new group is returned in count ( which may be 0). An error in parameter specification will result in a negative error status returned in count. The naming conventions for groups has been described earlier in section 3.3.1.

If the expr string is null (in C) or a single space (in FORTRAN), the group will consist of the columns referenced by the cols array, in the order that they occur; the ncols parameter indicates the number of columns in the list. An attempt to install column numbers that do not exist will result in a negative error status.

The default type is 'local', and so if any of these groups are to be stored in the file's label, then an explicit type of 'group' or 'unit' must be specified.

The expression string expr consists of a simple series of relative or "full-pathname" group names, separated by operators. If a given groupname appearing in an expression contains any characters other than alphanumeric, dollar$signs and under_score (and the colon for full-pathnames), then they must be quoted. To quote a name you may nest it between (parentheses), [brackets], {curly brackets}, 'single quotes' or "double quotes". The choice of quotation marks is only driven by the condition that the matching end-quote character not occur within the name being quoted. Here are some examples of group names as used within an expression:

(This   one  has   spaces  so  it  does)
[This one has (parens) in its name]
"$%^*(){} in double quotes"

The currently supported operators for group expressions are (&, |, and -) for ordered intersection, concatenization, and set-differencing (A but not B) respectively. The ( * and + ) characters may be used as an aliases for ( & and | ), respectively.

The expressions are evaluated immediately, from left to right, and no expression-grouping is (currently) permitted. If the group name is not in full-pathname format, the group will be searched for in the standard order.

Some examples of group-expressions:

format:BYTE & group:Image1

resulting group: All BYTE format columns belonging to group named "Image1"

$line | group:sample - [unit:(kg*m)/sec^2]	

resulting group: take all of the columns from local group $line, and all of group "sample", but then subtracting away any column which uses "(kg*m)/sec^2" as a unit of measurement. Note that the unit name was placed between brackets, as it contains the characters "*/^()".

Although both upper and lower case letters may be used in a group name, recognition of names during searches is case-insensitive.

Note that 'format' types may not be created or destroyed. IBISGroupDelete

status = IBISGroupDelete( ibis,type, name );
call ibis_group_delete( ibis,type, name,status)

ibis		input	integer
type		input	keyword
name		input	string
status		output	integer

type = { unit | group | local | any }, default=any

Delete an existing group of type type with name name. Note that 'format' groups are not allowed to be deleted. Be careful when using 'any' to delete a group: for example, if you have defined both a 'unit' and a 'local' group with the same name, you may delete the wrong one. The search order for 'any' is the reverse from that of IBISGroupFind: (locals, groups, units, formats), to insure that low-priority groups are found and deleted first. IBISGroupModify

status = IBISGroupModify( ibis,type, name, mod, cols, ncols );
call ibis_group_modify( ibis,type, name,mod, cols, ncols,status)

ibis		input	integer
type		input	keyword
name		input	string
mod			input	keyword
status		output	integer

type = {UNIT | GROUP | LOCAL | ANY } default=ANY

Modify an existing group of type type with name name, using the method mod. The append method appends the columns to the end of the list, in the order given. The insert mode inserts the columns, again the in same order, before the first element in the group. The REMOVE mode removes the named columns from the list. If the REMOVE action removes all the columns in the group, the group is deleted and will not appear in the file.

Be careful when using 'any' to modify a group: for example, if you have defined both a 'unit' and a 'local' group with the same name, you will modify the 'local' group, not the 'unit'. The search order for 'any' is the reverse from that of IBISGroupFind: (locals, groups, units, formats), to insure that low-priority groups are found and modified first. IBISGroupFind

count = IBISGroupFind(ibis,type,column,namelist,sgroup,numgroups, length);
count =  ibis_group_find(ibis,type,column, namelist, sgroup, numgroups)

ibis		input	integer
type		input	keyword
column		input	integer
namelist	output	string array
sgroup		input	integer
numgroups	input	integer
length		input	integer
count		output	integer

type = {FORMAT | UNIT | GROUP | LOCAL | ANY }, default=ANY

Find, count and/or retrieve in namelist the list of all groups to which the column column belongs. This is the complementary routine to the IBISColumnFind routine, which will return all columns belonging to a given group, and its parameters and return status operate in the same way.

The sgroup indicates the (one-based) index of the first column in the list to return in namelist, and numgroups indicates the number to return into namelist. The numgroups value may be zero, if all that is desired is the total count of groups found, otherwise the returned count value is the actual number of items put into namelist.

Since this is a 2-dimensional character array, the length parameter is provided in the C-interface to allow the specification of the inner dimension of the array.

If type is 'any', search all groups, and return the groupnames in the "full-pathname" (group:groupname) format. Otherwise, only the relative groupnames will be returned. IBISGroupTransfer

count = IBISGroupTransfer( in,out,type, incols,outcols,ncols);
coutn = ibis_group_transfer( in,out,type, incols,outcols,ncols,status)

in		input	integer
out		input	integer
type		input	keyword
incols		input	integer array
outcols	input	integer array
ncols		input	integer
count		output	integer

type = {UNIT | GROUP | LOCAL | ANY}, default=GROUP

Transfer all of the group memberships belonging to specified columns in IBIS file 'in' to the IBIS file 'out'. Transfer only the 'ncols' columns specified by the 'incols' column list, and transfer the group membership to the corresponding column in the 'outcols' list. If type=ANY, transfer all of the group memberships GROUP, UNIT and LOCAL, but not FORMAT. The count returns either a non-negative count of the number of columns processed, or a negative error status.