id="plperl-utility-functions">
  <title>Utility Functions in PL/Perl</title>

   <variablelist>
    <varlistentry>
     <term>
      <literal><function>elog(<replaceable>level</replaceable>, <replaceable>msg</replaceable>)</function></literal>
      <indexterm>
       <primary>elog</primary>
       <secondary>in PL/Perl</secondary>
      </indexterm>
     </term>
     <listitem>
      <para>
       Emit a log or error message. Possible levels are
       <literal>DEBUG</literal>, <literal>LOG</literal>, <literal>INFO</literal>,
       <literal>NOTICE</literal>, <literal>WARNING</literal>, and <literal>ERROR</literal>.
       <literal>ERROR</literal>
        raises an error condition; if this is not trapped by the surrounding
        Perl code, the error propagates out to the calling query, causing
        the current transaction or subtransaction to be aborted.  This
        is effectively the same as the Perl <literal>die</literal> command.
        The other levels only generate messages of different
        priority levels.
        Whether messages of a particular priority are reported to the client,
        written to the server log, or both is controlled by the
        <xref linkend="guc-log-min-messages"/> and
        <xref linkend="guc-client-min-messages"/> configuration
        variables. See <xref linkend="runtime-config"/> for more
        information.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <literal><function>quote_literal(<replaceable>string</replaceable>)</function></literal>
      <indexterm>
       <primary>quote_literal</primary>
       <secondary>in PL/Perl</secondary>
      </indexterm>
     </term>
     <listitem>
      <para>
        Return the given string suitably quoted to be used as a string literal in an SQL
        statement string. Embedded single-quotes and backslashes are properly doubled.
        Note that <function>quote_literal</function> returns undef on undef input; if the argument
        might be undef, <function>quote_nullable</function> is often more suitable.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <literal><function>quote_nullable(<replaceable>string</replaceable>)</function></literal>
      <indexterm>
       <primary>quote_nullable</primary>
       <secondary>in PL/Perl</secondary>
      </indexterm>
     </term>
     <listitem>
      <para>
        Return the given string suitably quoted to be used as a string literal in an SQL
        statement string; or, if the argument is undef, return the unquoted string "NULL".
        Embedded single-quotes and backslashes are properly doubled.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <literal><function>quote_ident(<replaceable>string</replaceable>)</function></literal>
      <indexterm>
       <primary>quote_ident</primary>
       <secondary>in PL/Perl</secondary>
      </indexterm>
     </term>
     <listitem>
      <para>
        Return the given string suitably quoted to be used as an identifier in
        an SQL statement string. Quotes are added only if necessary (i.e., if
        the string contains non-identifier characters or would be case-folded).
        Embedded quotes are properly doubled.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <literal><function>decode_bytea(<replaceable>string</replaceable>)</function></literal>
      <indexterm>
       <primary>decode_bytea</primary>
       <secondary>in PL/Perl</secondary>
      </indexterm>
     </term>
     <listitem>
      <para>
        Return the unescaped binary data represented by the contents of the given string,
        which should be <type>bytea</type> encoded.
        </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <literal><function>encode_bytea(<replaceable>string</replaceable>)</function></literal>
      <indexterm>
       <primary>encode_bytea</primary>