4.2 Calling Sequences
4.2.2 IBIS Column Operations
4.2.2.1 IBISColumnGet
4.2.2.2 IBISColumnSet
4.2.2.3 IBISColumnRead
4.2.2.4 IBISColumnWrite
4.2.2.5 IBISColumnNew
4.2.2.6 IBISColumnClear
4.2.2.7 IBISColumnDelete
4.2.2.8 IBISColumnFind
4.2.2.9 IBISColumnMove
A Column is a vertically oriented array of data. A column is a homogeneous dataset, consisting of a single data type, and as such will be translated into the logical native host format.
Column-oriented I/O is not buffered (other than VICAR internal buffering), and for row-oriented files this is a particularly inefficient operation; for such files converting them to column-oriented files may be the best approach. This is the trade-off for having efficient row I/O -- No Free lunches.
status = IBISColumnGet( ibis, name, value, column );
call ibis_column_get( unit, name, value, column, status )
ibis input integer
name input keyword
value input value
status output integer
name = {FORMAT | SIZE | U_FORMAT | U_SIZE }Get the named attribute of the specified column. Here is a brief description of the properties of an IBIS column:
FORMAT: keyword
Count: 1
Value={ {FORMAT_TYPE} }: Format of column elements stored in file.
SIZE: Integer
Count: 1
Value: Size (in bytes) of columns elements stored in file.
U_FORMAT: keyword
Count: 1
Value={ NONE | {FORMAT_TYPE} }: Format of translated column elements.
U_SIZE: Integer
Count: 1
Value: Size (in bytes) of translated column elements.Each column uses its own method of translation, which initially is the default host<-->native translation method. This method may be overridden on a column-by-column basis, using the IBISColumnSet routine, below. Note the additional 'u_format' type called 'none', which indicates that the data will be returned in a raw, unformatted array of bytes. Also note that for IBIS-1 format files, all columns have 4-byte elements, so that the only supported 'FORMAT' types are 'FULL', 'REAL', or 'A4', where the 'A4' is interpreted as 4 characters, no null delimiter, with space padding if necessary. The U_FORMAT string types are always null-delimited in C (and padded in FORTRAN).
status = IBISColumnSet( ibis, name, value, column );
call ibis_column_Set( ibis, name, value, column, status )
ibis input integer
name input keyword
value input value
column input integer
status output integer
name = {FORMAT | SIZE | U_FORMAT | U_SIZE }Set the name attribute of the specified column to value.
Changing the 'format' value to one requiring a larger amount of contiguous space per element may force the library to relocate the column in the file, copying in the process the old data. The definition of each attribute may be found in the IBISColumnGet section.
The 'u_format' value may take on the usual format names, but also the special name 'none', indicating that the data should be returned in its raw, unformatted state.
Also note that for IBIS-1 format files, all columns have 4-byte elements, so that the only supported 'FORMAT' types are 'FULL', 'REAL', or 'A4', where the 'A4' is interpreted as 4 characters, no null delimiter, with space padding if necessary. The U_FORMAT string types are always null-delimited in C (and padded in FORTRAN).
Example: This routine may be called for old IBIS-1 files (which have no formatting information in the file) to change the format-translation used in reading the column data, so long as the new 'format' has a size no larger than 4 bytes. For example, if a file is in IBIS-1 format, and column 7 (say) is known to contain 4 bytes of character data with no null-delimiter (the standard for IBIS-1 files) , it may be read in as an A4 column thusly:
char buffer[100][5]; /* 100 A4 values */ IBISColumnSet( ibis, ICOLUMN_FORMAT, "A4",7,status); /*4 bytes*/ IBISColumnSet( ibis, ICOLUMN_U_FORMAT, "A4",7,status); /* 5 bytes*/ IBISColumnRead( ibis, buffer, 7, 1, 100,status); /* 100 A4 rows */
This will guarantee that the data will be translated into a 4-character-plus-null string array (FORTRAN programs may read these in as CHARACTER*4 arrays).
Putting character data back into this column (without nullifying the fourth character) works the same way; calling IBISColumnWrite with the same translation setup will cause the 5-characters A4 buffers to be truncated to 4 valid characters, without the null.
status = IBISColumnRead(ibis,buffer,column,srow,nrows); call ibis_column_read(ibis,buffer,column,srow,nrows,status) ibis input integer buffer output value column input integer srow input integer nrows input integer status output integer
Read and translate a column of data into the local format defined by the 'u_format' attribute. The srow and nrows parameters must be specified, and are used to write out only part of a column at a time. A column may be read while records are open; however, this will cause the records to flush all of their buffers, and so it is not suggested in general to mix column and record operations.
status = IBISColumnWrite(ibis,buffer,column,srow,nrows); call ibis_column_write(ibis,buffer,column,srow,nrows,status) ibis input integer buffer input value array column input integer srow input integer nrows input integer status output integer
Translate and write a column of data from the column's current 'u_format' format. The srow and nrows parameters must be specified, and are used to write out only part of a column at a time. A column that is currently locked by a record may be directly written to using this routine; however it will cause all of the open records to flush their buffers immediately, and so it is not recommended in general to mix column and record operations.
status = IBISColumnNew(ibis,column,ncols,format);
call ibis_column_new(ibis,column,ncols,format,status)
ibis input integer
column input integer
ncols input string
format input keyword
status output integer
format = { {FORMAT_TYPE} }, default=<fmt_default>Create and insert ncols new columns of the given format with the first new column numbered column. All of the old columns from column on are pushed up and renumbered. The column value may be passed in as 0, if the new columns are to be placed after the last column. A column may be created at any time, and will not affect any open records. If the file's AUTO_INIT value is 'ON' (which is the default) the values of the column are initialized to zero. Otherwise, it is the responsibility of the client program to initialize the column values.
status = IBISColumnClear(ibis,column,ncols); call ibis_column_clear(ibis,column,ncols,status) ibis input integer column input integer ncols input string status output integer Clear (set to zero) all values in ncols columns, starting with column column. A column that is currently locked by a record may be cleared; however it will cause all of the open records to flush their buffers immediately, and so it is not recommended in general to mix column and record operations.
status = IBISColumnDelete(ibis,column,ncols); call ibis_column_delete(ibis,column,ncols,status) ibis input integer column input integer ncols input integer status output integer
Delete ncols columns, starting with the given column id. All of the later columns are dropped down and renumbered. This routine does not alter the file size or structure for IBIS-2 files, but merely deletes the column pointer from the label. IBIS-1 files, however, must have column data physically relocated, and so this will be an I/O intensive operation for old files. A column that is currently locked by a record may not be deleted; other columns which do not belong to any open records may be deleted, however.
count = IBISColumnFind( ibis, type, group, collist, scol, numcols );
count = ibis_column_find( ibis, type, group, collist, scol, numcols )
ibis input integer
type input keyword
group input string
collist output integer array
scol input integer
numcols input integer
count output integer
type = { GROUP | FORMAT | UNIT | ANY } default=ANYFind, count and/or retrieve in collist a list of some or all columns belonging to the type group named group. This is the complementary routine to the IBISGroupFind routine, which will return all groups containing a given column.
The scol indicates the index of the first column in the list to return in collist, and numcols indicates the maximum number of values to return to collist.
The returned count value indicates the number actually copied (which may be less than numcols), unless numcols was passed in as 0, in which case the total number of columns in group is returned.
If type is 'any', search all groups; the groupname may in this case be in "full-pathname" or a "group-expression" form if desired. Otherwise, only the columns in the type group will be returned. You may use the ITYPE_xxx preprocessor macro for this argument.
If no columns were found but the parameters passed in were valid, a 0 will be returned in count; otherwise the count will be a negative error-status value.
For example, to read in the first column (if any) in the file belonging to group "LINE", use the following:
count = IBISColumnFind( ibis,ITYPE_GROUP,"LINE", &col,1,1); if (count<0) IBISSignal( ibis, count, 1); if (count==1) IBISColumnRead( ibis, buffer, column, 1, 1);
status = IBISColumnMove(ibis,sourcecol,destcol,ncols); call ibis_column_move(ibis,sourcecol,destcol,ncols,status) ibis input integer sourcecol input integer destcol input integer ncols input string status output integer
Move the columns starting at sourcecol to the location starting at destcol, and renumber all of the other affected columns. This operation only changes column numbering, and does not physically move any data in the file. This will not confuse any currently defined groups or records, which do not use column numbers to keep track of columns. However, any variables used by client programs which have column id's in them may be invalid following this routine.
Note: this routine currently only works for IBIS-2 files. Passing an IBIS-1 file to this routine will result in an error status.