
<refentry id="ST_AsMARC21">
    <refnamediv>
        <refname>ST_AsMARC21</refname>
        <refpurpose>Returns geometry as a MARC21/XML record with a geographic datafield (034).</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
        <funcsynopsis>

            <funcprototype>
                <funcdef>
                    text
                    <function>ST_AsMARC21</function>
                </funcdef>
                <paramdef>
                    <type>geometry </type>
                    <parameter>geom</parameter>
                </paramdef>
                <paramdef choice="opt">
                    <type>text </type>
                    <parameter>format='hdddmmss'</parameter>
                </paramdef>
            </funcprototype>

        </funcsynopsis>
    </refsynopsisdiv>

    <refsection>
        <title>Description</title>

        <para>This function returns a MARC21/XML record with <ulink url="https://www.loc.gov/marc/bibliographic/bd034.html">Coded Cartographic Mathematical Data</ulink> representing the bounding box of a given geometry. 
        The <varname>format</varname> parameter allows to encode the coordinates in subfields <varname>$d</varname>,<varname>$e</varname>,<varname>$f</varname> and <varname>$g</varname> in all formats supported by the MARC21/XML standard. Valid formats are:</para>
        
        <itemizedlist>
           <listitem><para>cardinal direction, degrees, minutes and seconds (default): <varname>hdddmmss</varname></para></listitem>
           <listitem><para>decimal degrees with cardinal direction: <varname>hddd.dddddd</varname></para></listitem>
           <listitem><para>decimal degrees without cardinal direction: <varname>ddd.dddddd</varname></para></listitem>
           <listitem><para>decimal minutes with cardinal direction: <varname>hdddmm.mmmm</varname></para></listitem>
           <listitem><para>decimal minutes without cardinal direction: <varname>dddmm.mmmm</varname></para></listitem>
           <listitem><para>decimal seconds with cardinal direction: <varname>hdddmmss.sss</varname></para></listitem>
        </itemizedlist>
       
       <para>The decimal sign may be also a comma, e.g. <varname>hdddmm,mmmm</varname>.</para>
       <para>The precision of decimal formats can be limited by the number of characters after the decimal sign, e.g. <varname>hdddmm.mm</varname> for decimal minutes with a precision of two decimals.</para>      
       <para>This function ignores the Z and M dimensions.</para>

        <para>
            LOC MARC21/XML versions supported:
            <itemizedlist>
                <listitem>
                    <para><ulink url="https://www.loc.gov/standards/marcxml/">MARC21/XML 1.1</ulink></para>
                </listitem>
            </itemizedlist>
        </para>

        <para>Availability: 3.3.0 </para>

        <note>
            <para>This function does not support non lon/lat geometries, as they are not supported by the MARC21/XML standard (Coded Cartographic Mathematical Data).</para>
        </note>
        
        <note>
            <para>
                The MARC21/XML Standard does not provide any means to annotate the spatial reference system for Coded Cartographic Mathematical Data, which means that this information will be lost after conversion to MARC21/XML.
            </para>
        </note>

    </refsection>

    <refsection>
        <title>Examples</title>
        
        <para>Converting a <varname>POINT</varname> to MARC21/XML formated as hdddmmss (default)</para>
        <programlisting><![CDATA[
        
            SELECT ST_AsMARC21('SRID=4326;POINT(-4.504289 54.253312)'::geometry);
            
                              st_asmarc21                                                                                                                              
            -------------------------------------------------
            <record xmlns="http://www.loc.gov/MARC21/slim">
                <datafield tag="034" ind1="1" ind2=" ">
                    <subfield code="a">a</subfield>
                    <subfield code="d">W0043015</subfield>
                    <subfield code="e">W0043015</subfield>
                    <subfield code="f">N0541512</subfield>
                    <subfield code="g">N0541512</subfield>
                </datafield>
            </record>
            
        ]]>
        </programlisting>
        
        <para>Converting a <varname>POLYGON</varname> to MARC21/XML formated in decimal degrees</para>
        <programlisting><![CDATA[
        
            SELECT ST_AsMARC21('SRID=4326;POLYGON((-4.5792388916015625 54.18172660239091,-4.56756591796875 54.196993557130355,-4.546623229980469 54.18313300502024,-4.5792388916015625 54.18172660239091))'::geometry,'hddd.dddd');
            
            <record xmlns="http://www.loc.gov/MARC21/slim">
                <datafield tag="034" ind1="1" ind2=" ">
                    <subfield code="a">a</subfield>
                    <subfield code="d">W004.5792</subfield>
                    <subfield code="e">W004.5466</subfield>
                    <subfield code="f">N054.1970</subfield>
                    <subfield code="g">N054.1817</subfield>
                </datafield>
            </record>

        ]]>
        </programlisting>
        
        <para>Converting a <varname>GEOMETRYCOLLECTION</varname> to MARC21/XML formated in decimal minutes. The geometries order in the MARC21/XML output correspond to their order in the collection.</para>
        <programlisting><![CDATA[
        
            SELECT ST_AsMARC21('SRID=4326;GEOMETRYCOLLECTION(POLYGON((13.1 52.65,13.516666666666667 52.65,13.516666666666667 52.38333333333333,13.1 52.38333333333333,13.1 52.65)),POINT(-4.5 54.25))'::geometry,'hdddmm.mmmm');
            
                              st_asmarc21                                                                                                                              
            -------------------------------------------------
            <record xmlns="http://www.loc.gov/MARC21/slim">
                <datafield tag="034" ind1="1" ind2=" ">
                    <subfield code="a">a</subfield>
                    <subfield code="d">E01307.0000</subfield>
                    <subfield code="e">E01331.0000</subfield>
                    <subfield code="f">N05240.0000</subfield>
                    <subfield code="g">N05224.0000</subfield>
                </datafield>
                <datafield tag="034" ind1="1" ind2=" ">
                    <subfield code="a">a</subfield>
                    <subfield code="d">W00430.0000</subfield>
                    <subfield code="e">W00430.0000</subfield>
                    <subfield code="f">N05415.0000</subfield>
                    <subfield code="g">N05415.0000</subfield>
                </datafield>
            </record>

        ]]>
        </programlisting>
        
    </refsection>
    <refsection>
        <title>See Also</title>
        <para><xref linkend="ST_GeomFromMARC21" /></para>
    </refsection>
</refentry>

