 <?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<!-- $Id$ -->

<refentry id="gfs-pio-set-view-index.3">

<refentryinfo><date>1 May 2002</date></refentryinfo>

<refmeta>
<refentrytitle>gfs_pio_set_view_index</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>

<refnamediv id="name">
<refname>gfs_pio_set_view_index</refname>
<refpurpose>change file view to an individual fragment</refpurpose>
</refnamediv>
<refsynopsisdiv id="synopsis">
<funcsynopsis>
<funcsynopsisinfo format="linespecific">
#include &lt;gfarm/gfarm.h&gt;
</funcsynopsisinfo>

<funcprototype>
<funcdef>
  <function moreinfo="none"><returnvalue>char *</returnvalue>gfs_pio_set_view_index</function></funcdef>
    <paramdef>GFS_File <parameter moreinfo="none">gf</parameter></paramdef>
    <paramdef>int <parameter moreinfo="none">fragment_number</parameter></paramdef>
    <paramdef>int <parameter moreinfo="none">fragment_index</parameter></paramdef>
    <paramdef>char *<parameter moreinfo="none">host</parameter></paramdef>
    <paramdef>int <parameter moreinfo="none">flags</parameter></paramdef>
</funcprototype>


</funcsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para><function moreinfo="none">gfs_pio_set_view_index()</function> changes the process's view of the data
in the file specified by <parameter moreinfo="none">gf</parameter> to a file fragment with the index
<parameter moreinfo="none">fragment_index</parameter>.</para>

<para>When creating a new file, it is necessary to specify the total number
of file fragments <parameter moreinfo="none">fragment_number</parameter>.  Every parallel process
should specify the same <parameter moreinfo="none">fragment_number</parameter> for the corresponding
file.  When the file exists, <constant>GFARM_FILE_DONTCARE</constant> can be
specified.  If <parameter moreinfo="none">fragment_number</parameter> is different from the total
fragment number of the existent file, it is erroneous.</para>

<para><parameter moreinfo="none">host</parameter> is used for explicitly specifying a filesystem node.  If
<parameter moreinfo="none">host</parameter> is NULL, appropriate filesystem node is chosen.</para>

<para>Values of <parameter moreinfo="none">flag</parameter> are constructed by a bitwise-inclusive-OR of
the following list.</para>
<variablelist>

<varlistentry>
<term><constant>GFARM_FILE_SEQUENTIAL</constant></term>
<listitem>
<para>File will be accessed sequentially.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_FILE_REPLICATE</constant></term>
<listitem>
<para>File may be replicated to a local filesystem when accessing remotely.
This flag cannot be specified with <constant>GFARM_FILE_NOT_REPLICATE</constant>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_FILE_NOT_REPLICATE</constant></term>
<listitem>
<para>File may not be replicated to a local filesystem when accessing
remotely.  This flag cannot be specified with
<constant>GFARM_FILE_REPLICATE</constant>.</para>

</listitem>
</varlistentry>
</variablelist>

<para>By default, Gfarm files are accessed as a whole file in global file
view where each fragment can be seamlessly accessed.</para>

</refsect1>

<refsect1 id="return-values"><title>RETURN VALUES</title>
<variablelist>

<varlistentry>
<term><constant>NULL</constant></term>
<listitem>
<para>The function terminated successfully.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_NO_MEMORY</constant></term>
<listitem>
<para>Insufficient memory was available.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_OPERATION_NOT_PERMITTED</constant></term>
<listitem>
<para>The file is not a regular fragmented file.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_FRAGMENT_NUMBER_DOES_NOT_MATCH</constant></term>
<listitem>
<para>The total number of file fragments is different from the existence
one.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><constant>GFARM_ERR_INVALID_ARGUMENT</constant></term>
<listitem>
<para>Invalid arguments are specified, for instance,
<constant>GFARM_FILE_DONTCARE</constant> is specified as the total number of
fragments of a newly created file.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Others</term>
<listitem>
<para>An error except the above occurred.  The reason is shown by its
pointed strings.</para>
</listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1 id="see-also"><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gfs_pio_create</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfs_pio_set_view_local</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>

</refentry>

