Table of Contents

4.2.1 IBIS File-Level Routines

Contents
      4.2 Calling Sequences
            4.2.1 IBIS File-Level Routines
                  4.2.1.1 IBISFileOpen
                  4.2.1.2 IBISFileClose
                  4.2.1.3 IBISFileUnit
                  4.2.1.4 IBISFileUnitOpen
                  4.2.1.5 IBISFileGet
                  4.2.1.6 IBISFileSet
                  4.2.1.7 IBISFileClear

4.2.1.1 IBISFileOpen

status = IBISFileOpen( unit, ibis,mode, ncol,nrow, format, org );
call ibis_file_open( unit, ibis, mode, ncol, nrow, format, org,status )

unit		input	integer
ibis		output	integer
mode		input	keyword
ncol		input	integer
nrow		input	integer
format		input	keyword array
org		input	keyword
status		output	integer

mode = { READ | WRITE | OWRITE | UPDATE }
org = { ROW | COLUMN }, default=COLUMN
format = Array of { FORMAT_LIST },  default=<fmt_default>

Open a file for read/update/write access; the unit parameter is the VICAR unit acquired using xvunit/zvunit . The routine returns a file handle into variable ibis, which is to be used for all IBIS file-io, and returns the success/failure status value.

The format parameter array specifies the format of each column, if this is a new file. For the fortran routine ibis_file_open the format array may be an array of CHARACTER*n, or a single space ' ' if defaulted. For the C-level routine the format must be a 2-dimensional array of characters or a null pointer if defaulted. The valid format keywords, as well as the inner dimension of the format array are specified by the IFMT_xxx preprocessor macros.

The org parameter specifies whether a new file is to be organized with contiguous data elements from 'row' or 'column'. The IORG_xxx preprocessor macros may be used for this parameter. The default is 'column', which may be indicated by a null pointer (in C) or by a single space ' ' in fortran.

The mode parameter specifies whether the file is opened for 'read', 'write', 'owrite' or 'update'; the IMODE_xxx preprocessor macros may be used for this parameter.

For 'write' mode, IBISFileOpen creates the file and sets up the IBIS property label information; the ncol, nrow parameters specify the number of rows and columns of the file, and the keyword array format is used to specify the data format of each column. If the default format is desired for all columns, this may be indicated by passing into format a NULL pointer (for the C-routine) or a single space character (if FORTRAN). The default column format for a new IBIS file is REAL, unless overridden by IBISColumnSet, as described later.

For 'read' and 'update' modes, the four arguments ncol, nrow, format, and org are usually ignored; default values should be passed in to each of them. However, if the file being opened is a GRAPHICS-1 file, there is no NC (Dimension) information stored in the file, and there is no natural default value, so the ncol value must be supplied in IBISFileOpen. If it is not known beforehand whether this may be the case, it is best to call IBISFileUnit first, which scans the existing file, and then use IBISFileGet to determine its 'VERSION' and 'ORG'.

By definition, an 'IBIS-1' file with 'ROW' organization is a GRAPHICS-1 file, and will require a NC value. If one is not supplied IBISFileOpen will return an error status. As mentioned above, it is a good idea to provide a "G1DIM" parm in the PDF file to permit the specification of this value. The only time this might not be necessary is when the program does not have any imaginable applicability to GRAPHICS files.

There is one additional mode called 'owrite', which should only be invoked in case an IBIS-1 file needs to be created. This last mode is not recommended in general (and is included only for backward-compatibility), as the format-translation routines will cause the file I/O to be slower on non-VMS machines, the format is not very flexible or portable, and only REAL*4 columns are created (although this can be changed manually using IBISFileSet before creating the file, or IBISColumnSet after it is opened).

4.2.1.2 IBISFileClose

status = IBISFileClose( ibis, close_option );
call ibis_file_close( ibis, close_option, status )

ibis		input	integer
close_option	input	keyword
status		output	integer

close_option = { UKEEP | UDELETE }, default=UDELETE

This routine flushes all the IBIS record buffers of the ibis file, updates the label information, then closes the IBIS file. It is important to call this routine prior to exiting the program for a newly created or modified IBIS files, or else the relevant labels and data will not be correct.

The close_option keyword may be set to 'ukeep', if the client program intends to re-open the file descriptor later, using IBISFileUnitOpen. The default action is to delete the descriptor when the file is closed. The preprocessor macros ICLOSE_xxx may be used for this option.

When a file is closed with the 'ukeep' option, the descriptor preserves the VICAR unit, the 'nr', 'nc', 'org' 'mode', 'version' and 'formats' list of the file when it was closed. It loses all of the various groups (including units and locals) as well as the records associated with the open file. If the client program needs to preserve any of these groups, (for example, 'locals'), it can always call IBISFileGet to retrieve a complete list of the desired groups, and then for each group call IBISColumnFind to save the list of columns for that group. Then, after re-opening the file, this list may be passed to IBISGroupNew to re-install the group.

4.2.1.3 IBISFileUnit

status = IBISFileUnit( unit,ibis, mode, ncol,nrow, format, org );
call ibis_file_unit( unit, ibis, mode, ncol, nrow, format, org,status )

unit		input	integer
ibis		output	integer
mode		input	keyword
ncol		input	integer
nrow		input	integer
format		input	keyword array
org			input	string
status		output	integer

mode = { READ | WRITE | OWRITE | UPDATE }
org = { ROW | COLUMN }
format = Array of {  FORMAT_LIST  },  default=<fmt_default>

Create an IBIS file descriptor without opening file. The purpose of this routine is to allow a client program to modify the IBIS properties of the descriptor prior to physically opening/creating this file. Since the file referenced by the ibis descriptor is not yet opened, only a limited number of IBIS routines may be given this descriptor without returning a "file not open" status. The routines which can be used are IBISFileSet, IBISFileGet, which may be used to access and modify the current IBIS properties, and IBISFileUnitOpen, which opens/creates the IBIS file and allows the ibis descriptor to be used as normal.

For example, on creating a new IBIS file, if the format parameter is not specified, all of the columns will be formatted using the 'fmt_default' property of the IBIS file, which is initially set to 'REAL'. If a client program needs to create an IBIS file in which all columns are in 'DOUB' format, but without explicitly using the format parameter, it may do so as follows:

...
IBISFileUnit( unit, &ibis, "write", 20, 30, 0, 0 );
IBISFileSet( ibis, "fmt_default", "doub" );
IBISFileUnitOpen( ibis );
...

See the IBISFileSet routine for more information on other modifiable properties of IBIS file descriptors.

4.2.1.4 IBISFileUnitOpen

status = IBISFileUnitOpen( ibis);
call ibis_file_unit_open( ibis,status )

ibis		output	integer
status		output	integer

Open the file associated with a previously-created file descriptor for read/update/write access; the ibis parameter is the IBIS file descriptor acquired using IBISFileUnit.

4.2.1.5 IBISFileGet

count = IBISFileGet( ibis, name, value, sval, maxvals, length );
count = ibis_file_get(  ibis, name, value, sval, maxvals)

ibis		input	integer
name		input	keyword
value		output	value
sval		input	integer
maxvals		input	integer
length		input	integer
count		output	integer

name = { NR | NC | FORMATS | FMT_DEFAULT | TYPE | MODE |
	 UNITS | GROUPS | LOCALS | HOST | INTFMT | REALFMT |
     ORG |  TYPE | VUNIT | VERSION | AUTO_INIT
     PIX_FORMAT | PIX_HOST | PIX_NS | PIX_NL | PIX_RECSIZE }

Get the value of IBIS property name. The IBISFileGet/Set routines provide access to the IBIS property label of the opened IBIS file, and are the IBIS equivalent to the xvget and xlget routines for standard VICAR files. For multi-valued items, the sval parameter indicates the index of starting value, and maxvals indicates the maximum number of values to return in value.

Note that maxvals may be zero, if the only purpose is to determine the number of values in count. The value returned in count indicates the total number of values returned in value (which may be zero) or else a negative error status.

For the C-level routine, the length parameter is provided to allow the specification of the inner dimension of 2-dimensional string-valued arrays. Note that this is the size of the array element, and not the "strlen" length of the string.

Here is a brief description of the accessible properties of an IBIS file descriptor, including conditions in which the property may be set by IBISFileSet (The preprocessor macros IFILE_xxx, may be used for these) :

NR: Integer	
Count: 1	
Value: Number of Rows.
Setable: If not 'read' mode.

NC: Integer	
Count: 1	
Value: Number of Columns.
Setable: Yes. This is required for IBIS-1 files organized by ROWS, which do not have any explicit dimensioning. (This is the same as GRAPHICS-1 format). For all other formats in 'read' mode the NC value will be overridden and determined from the file contents.

ORG: keyword	
Count: 1	
Value={ ROW  |  COLUMN } : File organization.
Setable: Yes, if file not open. If the file version is 'IBIS-1' and the 'org' is changed to 'row' then this is a GRAPHICS-1 format, and will require that the client also set the 'NC' value before opening the file.

FORMATS: keyword array	
Count: NC	
Value=Array of { FORMAT_LIST } : Format of each column. This is an array of 5-character format names (in C, 5 chars + null).
Setable: Yes, if file not open and in 'write' or 'owrite' mode.

FMT_DEFAULT: keyword	
Count: 1	
Value={ FORMAT_LIST } : Default Format of new columns in this file, and the name of the format to be omitted in the IBIS property label.
Setable: Yes.

TYPE: String	
Count: 1	
Value:  Subtype of IBIS file (client defined).
Setable: If not 'read' mode.

MODE: keyword	
Count: 1	
Value={ READ  |  WRITE | UPDATE | OWRITE } : File open action.
Setable: If file not open.

UNITS: string array
Count: arbitrary
Value: The names of all the units of measurement used by at least one column in the file.
Setable: No.

GROUPS: string array
Count: arbitrary
Value: The names of all the GROUP's of columns defined for this file.
Setable: No.

LOCALS: string array
Count: arbitrary
Value: The names of the LOCAL groups of columns currently defined for this file.
Setable: No.

HOST: keyword
Count: 1	
Value={ <VICAR Host Names>} : This is the HOST name of the internal format representation used by all of the columns in the file, and is the same as the BHOST System label value.
Setable: If file not in 'read' mode. May also use NATIVE or LOCAL.

INTFMT:keyword
Count: 1	
Value={ LOW | HIGH } : This is the INTFMT format representation used by all of the integer-valued columns in the file, and is the same as the BINTFMT System label value.
Setable: If file not in 'read' mode. May also use NATIVE or LOCAL.

REALFMT:keyword
Count: 1	
Value={ VAX | IEEE | RIEEE } : This is the REALFMT format representation used by all of the real or complex-valued columns in the file, and is the same as the BREALFMT System label value.
Setable: If file not in 'read' mode. May also use NATIVE or LOCAL.

VUNIT: integer
Count: 1	
Value=The VICAR file unit referenced by this file descriptor.
Setable: No.

VERSION: string
Count: 1	
Value={ IBIS-1 | IBIS-2 }=version of this IBIS file.
Setable: Only if file is not open and in 'write' or 'owrite' mode. Setting this value is equivalent to changing the open MODE type between 'write' (for IBIS-2) and 'owrite' (for IBIS-1).

AUTO_INIT : keyword	
Count: 1	
Value={ ON | OFF }: Default=OFF for READ files, ON for all others. Indicates whether to initialize the column/row values, upon their creation, to zero and null strings.
Setable: If not in READ mode. 

PIX_FORMAT : keyword	
Count: 1	
Value={ FORMAT_LIST }: Format of Image Pixel Data (if any). Default=BYTE.
Setable: If file not open and in 'write' mode. Will fail for IBIS-1. In order to set PIX_FORMAT, you must first set PIX_NS, below. 

PIX_HOST : keyword	
Count: 1	
Value={ <VICAR Host Names> }: HOST Format of Image Pixel Data (if any), Default=NATIVE. This is completely independent of the IBIS HOST format, below.
Setable: If file not open and in 'write' mode. Will fail for IBIS-1. In order to set PIX_HOST, you must first set PIX_NS, below. You may also use 'NATIVE' or 'LOCAL'.

PIX_NS : Integer	
Count: 1	
Value=: Number of samples in Image Pixel Data (this determines the file's record size).
Setable: If file not open and in 'write' mode. Will fail for IBIS-1. If you set PIX_NS but do not set PIX_FORMAT or PIX_HOST, it will be BYTE, and the NATIVE host format.

PIX_NL : Integer	
Count: 1	
Value=: Number of image lines in Image Pixel Data, if any. 
Setable: No. (To append an image, re-open the file after creating the IBIS data, using xvopen/zvopen).

PIX_RECSIZE : Integer	
Count: 1	
Value=: The VICAR 'RECSIZE' of the File.
Setable: No. (To set the recordsize, specify the 'PIX_FORMAT' 'PIX_HOST' and 'PIX_NS' directly).

For access to column - specific properties (size, format...) use IBISColumnGet.

Example#1: To get the number of rows of a file:

C:
#include "ibisfile.h"
...
count = IBISFileGet( ibis, IFILE_NR, &nr, 1, 1, 0);

FORTRAN:
count = ibis_file_get( ibis, 'nr', nr, 1, 1)

Example#2 (FORTRAN): To print out a list of all the units of an open IBIS file:

nunits = ibis_file_get( ibis, 'units', ' ', 1, 0)
nunits = ibis_file_get( ibis, 'units', unames, 1, nunits)
do n=1,nunits
	! get the # and columns belonging to unit <unames> 
	ncols = ibis_column_find( ibis,'unit', ' ', clist, 1, 0)
	ncols = ibis_column_find( ibis,'unit',unames(n),clist, 1, ncols)

	! print out the label & #cols -- should check that ncols>0 
	write (*, '(A,I,A,A)' )
+	  'There are ',ncols,' columns labeled', unames(n)

	! print out the columns for this label
	do j=1,ncols
		write (*,'(I,A)') clist(j), ', '
	enddo
enddo

4.2.1.6 IBISFileSet

status = IBISFileSet( ibis, name, value, length );
call ibis_file_set( ibis, name, value, status )

ibis		input	integer
name		input	keyword
value		input	value
status		output	integer

name = { NR | NC | FORMATS | FMT_DEFAULT | TYPE | MODE |
	      HOST | INTFMT | REALFMT |
           ORG |  TYPE | VERSION | AUTO_INIT
           PIX_FORMAT | PIX_HOST | PIX_NS }

Set IBIS file property name for the file descriptor ibis. For descriptors with unopened files, such as those created by IBISFileUnit, the ibis properties will be installed when the file is opened/created by IBISFileUnitOpen. If the file exists, and is currently opened in a modifiable state, update the file contents and label structure immediately to reflect the changes. The length parameter in the C-interface is only required for multi-valued string arrays (e.g, 'formats') to specify the the inner dimension of the array.

The 'formats', 'version', and 'org' values can only be set if the file is not currently opened, and the file unit was is set for for 'write' or 'owrite' mode. The 'pix_xxx' can only be set if the file is not currently opened, and the file is in 'write' mode (ie, no IBIS-1 files).

The 'auto_init' attribute may be set to 'off' if you are creating a new IBIS file descriptor and would like to avoid the overhead of having the IBISFileUnitOpen routine initialize the file values. The client program must then take responsibility to set the file values itself.

The 'pix_xxx' values need only be changed if it is anticipated that a VICAR image of that format and line length will be appended later to the file. By default the format is set to BYTE and the NS value is set to a value which makes the record size appropriate for the specified IBIS column data. In order to change the 'pix_xxx' values, you must set the 'pix_ns' value first.

Changing 'nr' or 'nc' for currently open files in 'write' or 'owrite' will result in new rows/columns being created or the last ones deleted. If new columns need to be created, they will be in the format specified by the 'fmt_default' property of the ibis descriptor.

For a description of each of the values associated with each keyword name, see IBISFileGet.

For example, to set the default column format to FULL :

C:
#include "ibisfile.h"
IBISFileSet( ibis, IFILE_FMT_DEFAULT, IFMT_FULL  );

FORTRAN:
CALL IBIS_FILE_SET( IBIS, 'FMT_DEFAULT', 'FULL', STATUS)

4.2.1.7 IBISFileClear

status = IBISFileClear( ibis );
call ibis_file_clear( ibis, status )

ibis		input	integer
status		output	integer

Initializes all of the data in the file to zero (and null strings). This is done automatically when creating a new file, unless the 'AUTO_INIT' attribute of the file has been set to 'OFF' (the default is 'ON').