SECTION 6 -- IMAGE I/O FUNCTIONS

The image file access package manipulates disk-resident image files. A "line" is a fixed length record whose size and format are caller-controlled. An image file also contains label records whose size and format are caller-controlled.

A line is identified by channel number and line number within channel. Images are stored in channel-interleaved or channel-sequential format. In channel-interleaved format, the sequence of lines is:

[1,1], [2,1],...[C,1], [1,2], [2,2],...[C,2]...

where [c,l] represents line 1 of channel c and C is the number of channels. The sequence of lines for channel-sequential format is:

[1,1], [1,2],...[1,L], [2,1], [2,2],...[2,L]...

where L is the number of lines.

The file organization, number of channels, number of lines within each channel, and line size are caller-specified values.

If special line arrangements (e.g., pixel interleaved, band interleaved by group) must be stored in an image file, the caller can set the number of channels to one and implement the caller's own mapping between image package line numbers and the actual image line numbers.

Lines are stored starting on a sector boundary on disk so that any line may be directly accessed without intermediate buffering by the image access package. There are I_SECT bytes per sector.

Space is allocated in the file for label records. In addition to labels and data, the image access package reserves a sector for file characteristics (lines per channel, number of channels, number of label sectors, number of labels, size of each label record, and line size).

An image file control block is used to carry housekeeping information and to identify a file for reading and writing. After it is opened, the control block (structure IFCB) has the following information available to the caller:

(*ifcb).i_lines - lines per channel
(*ifcb).i_chans - number of channels
(*ifcb).i_linsz - bytes per line
(*ifcb).i_labs - number of label records
(*ifcb).i_labsz - bytes per label record
(*ifcb).i_org - the file organization, I_CI or I_CS
(*ifcb).i_start - sector number of the first image line (=2)

The image access package will malfunction if the image file control block is changed while a file is open.

For VMS, the include file associated with this package is $TAEINC:XIINC.INP. For UNIX, the file is $TAEINC/xiinc.inp.

6.1 i_clse - Close an Image File

VOID i_clse (ifcb, disp)

Function return:: No value is returned by this function.

Arguments:

```
ifcb: input/output, struct IFCB *ifcb;
```
Image file control block (setup when the image file is opened).
```
disp: in, FUNINT disp;
```
Disposition for the file when it's closed; I_DEL or I_SAVE.

i_clse closes the image file. After the close, the ifcb may be re-used for another file.

6.2 i_herr - Return Last Host-dependent Error Code

FUNCTION CODE i_herr (ifcb)

Function return:

Host-dependent error code associated with the last operation using the specified IFCB.

Argument:

```
ifcb: input/output, struct IFCB *ifcb;
```
Image file control block.

i_herr returns the host-dependent error code associated with the last operation using the ifcb.

6.3 i_opin - Open Existing File for Input or Input/Output.

CODE i_opin (ifcb, lun, hostname, type)

Function return:

SUCCESS - File was successfully opened.
P_FAIL - File could not be opened.

Arguments:

```
ifcb: out, struct IFCB *ifcb;
```
Image file control block.
```
lun: in, FUNINT lun;
```
Logical unit number (ignored for VMS).
```
hostname: in, TEXT hostname[];
```
Host filespec of file to open.
```
type: in, FUNINT type;
```
Open type (I_INPUT or I_INOUT).

i_opin opens an existing image file for direct access I/O.

6.4 i_opou - Open File for Output.

CODE iopou (ifcb, lun, hostname, org, chans, lines, 
                        linsiz, labels, labsiz)

Function return:

SUCCESS - File was successfully opened.
P_FAIL - File could not be opened.

Arguments:

```
ifcb: out, struct IFCB *ifcb;
```
Image file control block.
```
lun: in, FUNINT lun;
```
Logical unit number (ignored for VMS).
```
hostname: in, TEXT hostname[];
```
Host filespec of file to open.
```
org: in, FUNINT org;
```
File organization I_CI (channel-interleaved) or I_CS (channel-sequential).
```
chans: in, FUNINT chans;
```
Number of channels.
```
lines: in, FUNINT lines;
```
Number of lines per channel.
```
linsiz: in, FUNINT linsiz;
```
Bytes per line.
```
labels: in, FUNINT labels;
```
Number of label records.
```
labsiz: in, FUNINT labsiz;
```
Bytes per label record.

i_opou opens an image file for direct access output. i_opou creates a new file and opens the file for reading and/or writing.

6.5 i_rdlb - Read a Label Record

CODE i_rdlb (ifcb, buffer, labnum)

Function return:

SUCCESS - Label record successfully read.
P_FAIL - Label record could not be read.
I_NOLAB - Incorrect label number.

Arguments:

```
ifcb: in/out, struct IFCB *ifcb;
```
Image file control block.
```
buffer: in, GENPTR buffer;
```
Pointer to the buffer to receive the label record.
```
labnum: in, FUNINT labnum;
```
Label record number (1-n) where n is number of label records.

i_rdlb completes the reading of the label before returning to the calling program.

6.6 i_read - Initiate Read to an Image File

CODE i_read (ifcb, buffer, channel, line, lines)

Function return:

SUCCESS - Read was successfully completed.
P_FAIL - Read failed for unspecified reasons.
I_IVLIN - Invalid line specification.

Arguments:

```
ifcb: in/out, struct IFCB *ifcb;
```
Image file control block.
```
buffer: out, GENPTR buffer;
```
User's data receive buffer.
```
channel: in, FUNINT channel;
```
Channel number of line.
```
line: in, FUNINT line;
```
Line number within channel.
```
lines: in, FUNINT lines;
```
Number of lines to read.

i_read initiates a read request for line(s) of data; the input operation proceeds asynchronously with program execution. i_wait must be called to guarantee completion of the I/O.

If "lines" is greater than one, the several lines starting at the specified line are read. The user of the multi-line option must be cognizant of the file organization in order to know the identification of lines subsequent to the first. When several lines are read into "buffer", the lines subsequent to the first start on I_SECT boundaries, i.e., "buffer" must be allocated for:

LINSIZ = (*ifcb).i linsz
LINES * ((LINSIZ-1)/I _SECT + 1) * I_SECT bytes.

Multi-line I/O is more efficient than single line I/O.

6.7 i_wait - Wait for I/O (Read or Write) Completion on IFCB.

CODE i_wait (ifcb)

Function return:

SUCCESS - I/O was successfully completed.
P_FAIL - I/O could not be completed.

Argument:

```
ifcb: in/out, struct IFCB *ifcb;
```
Image file control block.

i_wait waits on completion of I/O initiated by i_read and i_write. Only one i_read or i_write may be active on a file at one time.

NOTE: Under UNIX, image file I/O function is synchronous. Therefore, i_wait simply returns the host code of the already completed I/O operation.

6.8 i_write - Initiate Write to an Image File

CODE i_write (ifcb, buffer, channel, line, lines)

Function return:

SUCCESS - Write was successfully completed.
P_FAIL - Write failed for unspecified reasons.
I_IVLIN - Invalid line specification.

Arguments:

```
ifcb: in/out, struct IFCB *ifcb;
```
Image file control block.
```
buffer: in, GENPTR buffer;
```
User's data buffer.
```
channel: in, FUNINT channel;
```
Channel number of line.
```
line: in, FUNINT line;
```
Line number within channel.
```
lines: in, FUNINT lines;
```
Number of lines to write.

i_write initiates a write request for line(s) of data; the output operation proceeds asynchronously with program execution. i_wait must be called to guarantee completion of the I/O.

If "lines" is greater than one, the several lines starting at the specified line are written. The user of the multi-line option must be cognizant of the file organization in order to know the identification of lines subsequent to the first. When several lines are written from "buffer", the lines subsequent to the first start on I_SECT boundaries, i.e., "buffer" must be allocated for:

LINSIZ = (*ifcb).i linsz
LINES * ((LINSIZ-1)/I_SECT + 1) * I_SECT bytes.

Multi-line I/O is more efficient than single line I/O.

6.9 i_wrlb - Write a Label Record

CODE i_wrlb (ifcb, buffer, labnum)

Function return:

SUCCESS - Write was successfully completed.
P_FAIL - Write failed for unspecified reasons.
I_NOLAB - Incorrect label number.

Arguments:

```
ifcb: in/out, struct IFCB *ifcb;
```
Image file control block.
```
buffer: in, GENPTR buffer;
```
User's data buffer.
```
labnum: in, FUNINT labnum;
```
Label record number (1-n) where n is number of label records.

i_wrlb completes writing the label record to disk before returning to the caller.

6.10 i_xtnd - Extend an Image File

CODE ixtnd (ifcb, channels, lines)

Function return:

SUCCESS - Extend was successfully completed.
P_FAIL - Extend failed for unspecified reasons.

Arguments:

```
ifcb: in/out, struct IFCB *ifcb;
```
Image file control block.
```
channels: in, FUNINT channels;
```
Number of channels to add.
```
lines: in, FUNINT lines;
```
Number of lines to add per channel.

i_xtnd allocates new space for an existing file. The ifcb must have been previously opened in one of the following ways:

i_opin (open existing file) with "type" argument set to i_inout.
i_opou (create new file).

For a channel-sequential image file, the "lines" argument is typically zero and the "channels" argument is the number of new channels to be appended to the file. In such a case, i_xtnd allocates space to hold L*channels new image lines (where L is the number of lines per channel as declared in the "lines" argument of the i_opou call).

For a channel-interleaved image file, the "channels" argument is typically zero and the "lines" argument is the number of new line groups to be appended. In such a case, i_xtnd allocates space to hold C*lines new image lines (where C is the number of channels as declared in the "chans" argument of the i_opou call).

Though not necessarily recommended, i_xtnd honors request to change the number of lines in a channel-sequential files or to change the number of channels in a channel-interleaved files. When such an i_xtnd call is made, image lines which exist in the file are effectively "re-identified," i.e., the lines must be retrieved using a different line/channel identification than when the lines were written.