<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="stdin" xmlns="http://docbook.org/ns/docbook" version="5.0">
  <!--
                    Header
  -->
  <refmeta>
    <refentrytitle>RD_AddCut</refentrytitle>
    <manvolnum>7</manvolnum>
    <refmiscinfo class='source'>October 2015</refmiscinfo>
    <refmiscinfo class='manual'>Rivendell C Library Manual</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>rd_addcut</refname>
    <refpurpose>Rivendell Add Cut C Library Function</refpurpose>
  </refnamediv>
  <info>
    <author>
      <personname>
        <firstname>Todd</firstname>
        <surname>Baker</surname>
        <email>bakert@rfa.org</email>
      </personname>
      <contrib>Rivendell C Library Author</contrib>
    </author>
  </info>

  <!--
                    Body
  -->
  <refsynopsisdiv id='synopsis'>
    <funcsynopsis>
    <funcsynopsisinfo>#include &lt;rivwebcapi/rd_addcut.h&gt;</funcsynopsisinfo>
    <funcprototype>
    <funcdef>int <function>RD_AddCut</function></funcdef>
      <paramdef> struct rd_cut * <parameter>cut[]</parameter></paramdef>
      <paramdef>const char <parameter>hostname[]</parameter></paramdef>
      <paramdef>const char <parameter>username[]</parameter></paramdef>
      <paramdef>const char <parameter>passwd[]</parameter></paramdef>
      <paramdef>const char <parameter>ticket[]</parameter></paramdef>
      <paramdef>const unsigned <parameter>cartnumber</parameter></paramdef>
      <paramdef>const char <parameter>user_agent[]</parameter></paramdef>
      <paramdef>unsigned * <parameter>numrecs</parameter></paramdef>
    </funcprototype> 
    </funcsynopsis>

  </refsynopsisdiv>

  <refsect1 id='description'><title>Description</title>
  <para>
    <command>RD_AddCut</command> is  the function to use
    to add a cut to an existing Rivendell Database.
  </para>
  <para>
    This function adds a cut to the cart number entered into the Rivendell database on hostname. The cut will be created with default values listed below.
  </para>
  <table xml:id="ex.addcut" frame="all">
    <title>RD_AddCut function call fields</title>
    <tgroup cols="4" align="left" colsep="1" rowsep="1">
      <colspec colname="FIELD NAME" />
      <colspec colname="FIELD TYPE" />
      <colspec colname="MEANING" />
      <colspec colname="REMARKS" />
      <thead>
        <row>
          <entry>
            FIELD NAME
          </entry>
          <entry>
            FIELD TYPE
          </entry>
          <entry>
            MEANING
          </entry>
          <entry>
            REMARKS
          </entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>
            *rd_cut
          </entry>
          <entry>
          Pointer to rd_cut structure
          </entry>
          <entry>
            Memory location to store cut information
          </entry>
          <entry>
            Mandatory
          </entry>
        </row>
        <row>
          <entry>
            hostname
          </entry>
          <entry>
          Character Array
          </entry>
          <entry>
            Name Of Rivendell DB Host
          </entry>
          <entry>
            Mandatory
          </entry>
        </row>
        <row>
          <entry>
            username
          </entry>
          <entry>
          Character Array
          </entry>
          <entry>
            Rivendell User Name
          </entry>
          <entry>
            Mandatory When NO Ticket Provided.
          </entry>
        </row>
        <row>
          <entry>
            passwd
          </entry>
          <entry>
          Character Array
          </entry>
          <entry>
            Rivendell User Password
          </entry>
          <entry>
            Mandatory When NO Ticket Provided.
          </entry>
        </row>
        <row>
          <entry>
            ticket
          </entry>
          <entry>
          Character Array
          </entry>
          <entry>
            Rivendell Authentification Ticket
          </entry>
          <entry>
            Mandatory When NO User/Password Pair Provided.
          </entry>
        </row>
        <row>
          <entry>
            cartnumber
          </entry>
          <entry>
          unsigned integer
          </entry>
          <entry>
            Cart Number
          </entry>
          <entry>
            Mandatory
          </entry>
        </row>
        <row>
          <entry>
            user_agent
          </entry>
          <entry>
          Character Array
          </entry>
          <entry>
            User Agent Value put into HTTP request
          </entry>
          <entry>
            Optional (default is Rivendell-C-API/x.x.x)
          </entry>
        </row>
        <row>
          <entry>
            *numrecs
          </entry>
          <entry>
          pointer to integer
          </entry>
          <entry>
            memory location for number of records returned
          </entry>
          <entry>
            Mandatory
          </entry>
        </row>
      </tbody>
    </tgroup>
  </table>

  <para>
    When successful function will return the number of records sent (numrecs) and a rd_cut structure which 
    is stored in the provided memory locations. The rd_cut structure has the following fields:
  </para>
  <programlisting>
    struct rd_cut {
          char cut_name[11];                  	/* Default is: CART###_CUT### */
          unsigned cut_cart_number;		/* Cart Number */
          unsigned cut_cut_number;		/* Next available Cut Number */
          int cut_evergreen;                    /* Default is: False */
          char cut_description[257];		/* Default is: Cut ### */
          char cut_outcue[257];			/* Default is: NULL */
          char cut_isrc[49];			/* Default is: NULL */
          char cut_isci[129];			/* Default is: NULL */
          unsigned  cut_length;			/* Default is: 0 */
          struct tm cut_origin_datetime;	/* Default is: NULL */
          struct tm cut_start_datetime;		/* Default is: NULL */
          struct tm cut_end_datetime;		/* Default is: NULL */
          int cut_sun;				/* Default is: true */
          int cut_mon;				/* Default is: true */
          int cut_tue;				/* Default is: true */
          int cut_wed;				/* Default is: true */
          int cut_thu;				/* Default is: true */
          int cut_fri;				/* Default is: true */
          int cut_sat;				/* Default is: true */
          char cut_start_daypart[14];		/* Default is: NULL */
          char cut_end_daypart[14];		/* Default is: NULL */
          char cut_origin_name[257];		/* Default is: NULL */
          unsigned cut_weight;			/* Default is: 1 */
          struct tm cut_last_play_datetime; 	/* Default is: NULL */
          unsigned cut_play_counter;		/* Default is: 0 */
          unsigned cut_local_counter;		/* Default is: 0 */
          unsigned cut_validity;		/* Default is: 0 */
          unsigned cut_coding_format;		/* Default is: 0 */
          unsigned cut_sample_rate;		/* Default is: 0 */
          unsigned cut_bit_rate;		/* Default is: 0 */
          unsigned cut_channels;		/* Default is: 2 */
          int cut_play_gain;			/* Default is: 0 */
          int cut_start_point;			/* Default is: -1 */
          int cut_end_point;			/* Default is: -1 */
          int cut_fadeup_point;			/* Default is: -1 */
          int cut_fadedown_point;		/* Default is: -1 */
          int cut_segue_start_point;		/* Default is: -1 */
          int cut_segue_end_point;		/* Default is: -1 */
          int cut_segue_gain;			/* Default is: -3000 */
          int cut_hook_start_point;		/* Default is: -1 */
          int cut_hook_end_point;		/* Default is: -1 */
          int cut_talk_start_point;		/* Default is: -1 */
          int cut_talk_end_point;		/* Default is: -1 */
    };

  </programlisting>

  </refsect1>
  <refsect2 id='returns'><title>RETURN VALUE</title>
    <para>
      On success, zero is returned. Using the provided parameters an rd_cut
structure is returned and the number of records is returned.
    </para>
    <para>
      If a server error occurs a -1 is returned.
      If a client error occurs a specific error number is returned.
    </para>
  </refsect2>
  <refsect3 id='errors'><title>ERRORS</title>
    <para>
      400          Missing Cart Numer.
    </para>
    <para>
      403          Invalid User Authentification.
    </para>
    <para>
      404          No Such Cart Exists or Invalid Permissions.
    </para>
    <para>
      500          Unable to Create Cut - No New Cuts.
    </para>
    <para>
      nnn  Unknown Error Occurred.
    </para>
  </refsect3>
     
</refentry>
