cvs: phpdoc /de/functions errorfunc.xml info.xml ldap.xml vmailmgr.xml wddx.xml /en/functions printer.xml /es/chapters install.xml /es/functions
strings.xml /es/language basic-syntax.xml constants.xml control-structures.xml expressions.xml functions.xml operators.xml /fr/functions bzip2.xml
/it/features error-handling.xml remote-files.xml /it/functions mssql.xml pgsql.xml uodbc.xml /pt_BR/functions url.xml

jeroen Sat Jul 7 19:11:56 2001 EDT Modified files: /phpdoc/de/functions errorfunc.xml info.xml ldap.xml vmailmgr.xml wddx.xml /phpdoc/en/functions printer.xml /phpdoc/es/chapters install.xml /phpdoc/es/functions strings.xml /phpdoc/es/language basic-syntax.xml constants.xml control-structures.xml expressions.xml functions.xml operators.xml /phpdoc/fr/functions bzip2.xml /phpdoc/it/features error-handling.xml remote-files.xml /phpdoc/it/functions mssql.xml pgsql.xml uodbc.xml /phpdoc/pt_BR/functions url.xml Log: Fix windows/macintosh newlines to unix ones. I left alone japanese and other languages with 'strange characters'

Index: phpdoc/de/functions/errorfunc.xml diff -u phpdoc/de/functions/errorfunc.xml:1.4 phpdoc/de/functions/errorfunc.xml:1.5 --- phpdoc/de/functions/errorfunc.xml:1.4 Sat Jul 7 18:16:52 2001 +++ phpdoc/de/functions/errorfunc.xml Sat Jul 7 19:11:19 2001 @@ -22,173 +22,173 @@ </para> </partintro> - <refentry id="function.error-log"> - <refnamediv> - <refname>error_log</refname> - <refpurpose>Sendet eine Fehlermeldung</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>error_log</function></funcdef> - <paramdef>string <parameter>message</parameter></paramdef> - <paramdef>int <parameter>message_type</parameter></paramdef> - <paramdef>string <parameter><optional>destination</optional></parameter></paramdef> - <paramdef>string <parameter><optional>extra_headers</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Sendet eine Fehlermeldung an das Log-File des Webservers, einen - <acronym>TCP</acronym> Port oder eine Datei. Der erste Parameter, - <parameter>message</parameter>, ist die Fehlermeldung, die - mitgeschrieben werden soll. Der zweite Parameter, - <parameter>message_type</parameter> gibt an, wo die Meldung - abgelegt werden soll: - <table> - <title><function>error_log</function> Typem</title> - <tgroup cols="2"> - <tbody> - <row> - <entry>0</entry> - <entry> - <parameter>Message</parameter> wird mit Hilfe des internen - Log-Systems des Betriebssystemes oder einer Datei - geschrieben, je nachdem, wie <link - linkend="ini.error-log">error_log</link> eingestellt ist. - </entry> - </row> - <row> - <entry>1</entry> - <entry> - <parameter>Message</parameter> wird via Email an die Adresse - gesendet, die mit <parameter>destination</parameter> - amnngegeben wurde. Dies ist der einzige Punkt, bei dem der - vierte Parameter <parameter>extra_headers</parameter> - verwendet wird. Die Nachricht verwendet die selbe interne - Funktion wie <function>mail</function>. - </entry> - </row> - <row> - <entry>2</entry> - <entry> - <parameter>Message</parameter> wird über den PHP-Debugger - gesendet. Diese Option ist nur verfügbar, wenn <link - linkend="install.configure.enable-debugger">der Debugger gestartet - wurde</link>. Ist das der Fall, so wird mit dem - <parameter>destination</parameter> Parameter der Hostname - oder die IP-Adresse gesetzt. Optional auch der Port, unter - dem der Debugger läuft. - </entry> - </row> - <row> - <entry>3</entry> - <entry> - <parameter>Message</parameter> wird an die Datei angefügt, - die mit <parameter>destination</parameter> angegeben wurde. - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - <example> - <title><function>error_log</function> Beispiele</title> - <programlisting role="php"> -// Server sendet eine Nachricht an den Administrator, -// daß keine Verbindung zur Datenbank möglich ist. -if (!Ora_Logon($username, $password)) { - error_log ("Oracle database not available!", 0); -} - -// Server sendet eine Nachricht an den Administrator, daß FOO langsam ausgeht -if (!($foo = allocate_new_foo()) { - error_log ("Big trouble, we're all out of FOOs!", 1, - "operator@mydomain.com"); -} - -// AndereMöglichkeiten, error_log() aufzurufen: -error_log ("You messed up!", 2, "127.0.0.1:7000"); -error_log ("You messed up!", 2, "loghost"); -error_log ("You messed up!", 3, "/var/tmp/my-errors.log"); - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.error-reporting"> - <refnamediv> - <refname>error_reporting</refname> - <refpurpose> - Gibt an, wie PHP-Fehlermeldungen gezeigt werden - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>error_reporting</function></funcdef> - <paramdef>int <parameter><optional>level</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Setzt die Stufe von PHP's Fehlermeldungen. Diese Stufe ist der - Fehlermeldung hängt von den folgenden Werten ab. (Hinter den - folgenden Links verbirgt sich die Bedeutung der internen Werte): - <table> - <title><function>error_reporting</function> Werte</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Werte</entry> - <entry>interne Namen</entry> - </row> - </thead> - <tbody> - <row> - <entry>1</entry> - <entry> - <link linkend="internal.e-error">E_ERROR</link> - </entry> - </row> - <row> - <entry>2</entry> - <entry> - <link linkend="internal.e-warning">E_WARNING</link> - </entry> - </row> - <row> - <entry>4</entry> - <entry> - <link linkend="internal.e-parse">E_PARSE</link> - </entry> - </row> - <row> - <entry>8</entry> - <entry> - <link linkend="internal.e-notice">E_NOTICE</link> - </entry> - </row> - <row> - <entry>16</entry> - <entry> - <link linkend="internal.e-core-error">E_CORE_ERROR</link> - </entry> - </row> - <row> - <entry>32</entry> - <entry> - <link linkend="internal.e-core-warning">E_CORE_WARNING</link> - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - </refsect1> - </refentry> + <refentry id="function.error-log"> + <refnamediv> + <refname>error_log</refname> + <refpurpose>Sendet eine Fehlermeldung</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>error_log</function></funcdef> + <paramdef>string <parameter>message</parameter></paramdef> + <paramdef>int <parameter>message_type</parameter></paramdef> + <paramdef>string <parameter><optional>destination</optional></parameter></paramdef> + <paramdef>string <parameter><optional>extra_headers</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Sendet eine Fehlermeldung an das Log-File des Webservers, einen + <acronym>TCP</acronym> Port oder eine Datei. Der erste Parameter, + <parameter>message</parameter>, ist die Fehlermeldung, die + mitgeschrieben werden soll. Der zweite Parameter, + <parameter>message_type</parameter> gibt an, wo die Meldung + abgelegt werden soll: + <table> + <title><function>error_log</function> Typem</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>0</entry> + <entry> + <parameter>Message</parameter> wird mit Hilfe des internen + Log-Systems des Betriebssystemes oder einer Datei + geschrieben, je nachdem, wie <link + linkend="ini.error-log">error_log</link> eingestellt ist. + </entry> + </row> + <row> + <entry>1</entry> + <entry> + <parameter>Message</parameter> wird via Email an die Adresse + gesendet, die mit <parameter>destination</parameter> + amnngegeben wurde. Dies ist der einzige Punkt, bei dem der + vierte Parameter <parameter>extra_headers</parameter> + verwendet wird. Die Nachricht verwendet die selbe interne + Funktion wie <function>mail</function>. + </entry> + </row> + <row> + <entry>2</entry> + <entry> + <parameter>Message</parameter> wird über den PHP-Debugger + gesendet. Diese Option ist nur verfügbar, wenn <link + linkend="install.configure.enable-debugger">der Debugger gestartet + wurde</link>. Ist das der Fall, so wird mit dem + <parameter>destination</parameter> Parameter der Hostname + oder die IP-Adresse gesetzt. Optional auch der Port, unter + dem der Debugger läuft. + </entry> + </row> + <row> + <entry>3</entry> + <entry> + <parameter>Message</parameter> wird an die Datei angefügt, + die mit <parameter>destination</parameter> angegeben wurde. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + <example> + <title><function>error_log</function> Beispiele</title> + <programlisting role="php"> +// Server sendet eine Nachricht an den Administrator, +// daß keine Verbindung zur Datenbank möglich ist. +if (!Ora_Logon($username, $password)) { + error_log ("Oracle database not available!", 0); +} + +// Server sendet eine Nachricht an den Administrator, daß FOO langsam ausgeht +if (!($foo = allocate_new_foo()) { + error_log ("Big trouble, we're all out of FOOs!", 1, + "operator@mydomain.com"); +} + +// AndereMöglichkeiten, error_log() aufzurufen: +error_log ("You messed up!", 2, "127.0.0.1:7000"); +error_log ("You messed up!", 2, "loghost"); +error_log ("You messed up!", 3, "/var/tmp/my-errors.log"); + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.error-reporting"> + <refnamediv> + <refname>error_reporting</refname> + <refpurpose> + Gibt an, wie PHP-Fehlermeldungen gezeigt werden + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>error_reporting</function></funcdef> + <paramdef>int <parameter><optional>level</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Setzt die Stufe von PHP's Fehlermeldungen. Diese Stufe ist der + Fehlermeldung hängt von den folgenden Werten ab. (Hinter den + folgenden Links verbirgt sich die Bedeutung der internen Werte): + <table> + <title><function>error_reporting</function> Werte</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Werte</entry> + <entry>interne Namen</entry> + </row> + </thead> + <tbody> + <row> + <entry>1</entry> + <entry> + <link linkend="internal.e-error">E_ERROR</link> + </entry> + </row> + <row> + <entry>2</entry> + <entry> + <link linkend="internal.e-warning">E_WARNING</link> + </entry> + </row> + <row> + <entry>4</entry> + <entry> + <link linkend="internal.e-parse">E_PARSE</link> + </entry> + </row> + <row> + <entry>8</entry> + <entry> + <link linkend="internal.e-notice">E_NOTICE</link> + </entry> + </row> + <row> + <entry>16</entry> + <entry> + <link linkend="internal.e-core-error">E_CORE_ERROR</link> + </entry> + </row> + <row> + <entry>32</entry> + <entry> + <link linkend="internal.e-core-warning">E_CORE_WARNING</link> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </refsect1> + </refentry> <refentry id="function.restore-error-handler"> <refnamediv> Index: phpdoc/de/functions/info.xml diff -u phpdoc/de/functions/info.xml:1.18 phpdoc/de/functions/info.xml:1.19 --- phpdoc/de/functions/info.xml:1.18 Sat Jul 7 18:16:59 2001 +++ phpdoc/de/functions/info.xml Sat Jul 7 19:11:19 2001 @@ -1,803 +1,803 @@ - <reference id="ref.info"> - <title>PHP Optionen und Informationen</title> - <titleabbrev>PHP Optionen/Informationen</titleabbrev> - - <refentry id="function.extension-loaded"> - <refnamediv> - <refname>extension_loaded</refname> - <refpurpose>Zeigt an, ob eine Bibliothek geladen wurde</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>extension_loaded</function></funcdef> - <paramdef>string <parameter>name</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Ist wahr, wenn die Bibliothek, die mit - <parameter>name</parameter> definiert wurde, geladen ist. Einen - Überblick über die verschiedenen Bibliotheken erhält mal mit - <function>phpinfo</function>. - </simpara> - <para> - Siehe auch <function>phpinfo</function>. - <note> - <para> - Diese Funktion wurde mit Version 3.0.10 eingeführt. - </para> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.getenv"> - <refnamediv> - <refname>getenv</refname> - <refpurpose>Zeigt den Wert einer Umgebungsvariablen an</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>getenv</function></funcdef> - <paramdef>string <parameter>varname</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Zeigt den Wert der Umgebungsvariablen - <parameter>varname</parameter> an oder &false; bei einem Fehler. - <informalexample> - <programlisting role="php"> -$ip = getenv ("REMOTE_ADDR"); // get the ip number of the user - </programlisting> - </informalexample> - </para> - <para> - Eine Liste aller Umgebungsvariablen wird mit - <function>phpinfo</function> angezeigt. Ein Überlick über viele - Umgebungsvariablen und deren Bedeutung findet sich unter den - <ulink url="&url.cgispecs;">CGI Spezificationen</ulink>, speziell - auf der Seite der <ulink url="&url.cgispec;">Umgebungsvariablen - </ulink>. - </para> - </refsect1> - </refentry> - - <refentry id="function.get-cfg-var"> - <refnamediv> - <refname>get_cfg_var</refname> - <refpurpose> - Zeigt den Wert einer Option der PHP-Konfiguration - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>get_cfg_var</function></funcdef> - <paramdef>string <parameter>varname</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Zeigt den derzeitigen Wert der Variablen der PHP-Konfiguration, - die mit <parameter>varname</parameter> ausgewählt wurde oder - &false; bei einem Fehler. - </simpara> - <simpara> - Bringt keine Informationen über die Konfiguration, mit der PHP - kompilert wurde, oder die aus der Apache-Konfiguration gelesen - wird (mittels der php3_configuration_option Anweisungen). - </simpara> - <simpara> - Um herauszubekommen, ob ein <link - linkend="configuration.file">configuration file</link>, benutzt - wird, sollte versucht werden, den Wert der cfg_file_path - Einstellung zu erhalten. Ist dieser Wert verfügbar, wird eine - Konfigurationsdatei verwendet. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.get-current-user"> - <refnamediv> - <refname>get_current_user</refname> - <refpurpose> - Den Besitzer des aktuellen PHP-Scripts anzeigen. - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>get_current_user</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Zeigt den Namen des Besitzers des aktuellen PHP-Scripts an. - </simpara> - <simpara> - Siehe auch <function>getmyuid</function>, - <function>getmypid</function>, <function>getmyinode</function>, - und <function>getlastmod</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.get-magic-quotes-gpc"> - <refnamediv> - <refname>get_magic_quotes_gpc</refname> - <refpurpose> - Zeigt die aktuelle Konfiguration von magic quotes gpc - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>long <function>get_magic_quotes_gpc</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Zeigt die aktuelle Konfiguration von - <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>. - (0 für aus, 1 für an). - </simpara> - <simpara> - Siehe auch <function>get_magic_quotes_runtime</function> und - <function>set_magic_quotes_runtime</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.get-magic-quotes-runtime"> - <refnamediv> - <refname>get_magic_quotes_runtime</refname> - <refpurpose> - Zeigt die aktuelle Konfiguration von magic_quotes_runtime - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef> - Long <function>get_magic_quotes_runtime</function> - </funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Zeigt die aktuelle Konfiguration von - <link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>. - (0 für aus, 1 für an). - </simpara> - <simpara> - Siehe auch <function>get_magic_quotes_gpc</function> und - <function>set_magic_quotes_runtime</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.getlastmod"> - <refnamediv> - <refname>getlastmod</refname> - <refpurpose> - Zeigt die Uhrzeit der letzten Änderung einer Seite - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>getlastmod</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <para> - Zeigt die Uhrzeit der letzten Änderung der aktuellen Seite. Der - Wert wird als Unix-Timestamp angezeigt, welcher für - <function>date</function> benutzt werden kann. Bringt &false; bei - einem Fehler. - <example> - <title><function>getlastmod</function> Beispiel</title> - <programlisting role="php"> -// outputs e.g. 'Last modified: March 04 1998 20:43:59.' -echo "Last modified: ".date ("F d Y H:i:s.", getlastmod()); - </programlisting> - </example> - </para> - <para> - Siehe auch <function>date</function>, - <function>getmyuid</function>, - <function>get_current_user</function>, - <function>getmyinode</function> und - <function>getmypid</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.getmyinode"> - <refnamediv> - <refname>getmyinode</refname> - <refpurpose>Gibt den Inode des aktuellen Skripts aus</refpurpose> - </refnamediv> - <refsect1> - <title>Beispiel</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>getmyinode</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <para> - Zeigt den inode des aktuellen Scripts oder &false; bei einem Fehler. - </para> - <para> - Siehe auch <function>getmyuid</function>, - <function>get_current_user</function>, - <function>getmypid</function> und - <function>getlastmod</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.getmypid"> - <refnamediv> - <refname>getmypid</refname> - <refpurpose>Zeigt die ID des PHP-Prozesses</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>getmypid</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <para> - Zeigt die aktuelle ID des PHP-Prozesses oder &false; bei einem - Fehler. - </para> - <para> - Achtung: Wenn PHP als Server-Modul läuft, ist es nicht - garantiert, dass Scripts unter verschiedenen PIDs laufen. - </para> - <para> - Siehe auch <function>getmyuid</function>, - <function>get_current_user</function>, - <function>getmyinode</function> und - <function>getlastmod</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.getmyuid"> - <refnamediv> - <refname>getmyuid</refname> - <refpurpose> - Zeigt die UID des Besitzers eines PHP-Scripts - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>getmyuid</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Zeigt die User-ID des aktuellen Scripts oder &false; bei einem - Fehler. - </simpara> - <simpara> - Siehe auch <function>getmypid</function>, - <function>get_current_user</function>, - <function>getmyinode</function> und - <function>getlastmod</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.getrusage"> - <refnamediv> - <refname>getrusage</refname> - <refpurpose> - Zeigt den aktuellen Ressourcenverbrauch an - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>getrusage</function></funcdef> - <paramdef>int <parameter><optional>who</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Dies ist eine Schnittstlle zu getrusage(2). Stellt ein - assoziatives Array mit den Daten zur Verfügung, die der - Systemaufruf ausgibt. Wenn who 1 ist, wird getusage mit - RUSAGE_CHILDREN aufgerufen. - </para> - <para> - Alle Einträge können über ihre Dukumentenfeldernamen aufgerufen - werden. - <example> - <title><function>getrusage</function> Beispiel</title> - <programlisting role="php"> -$dat = getrusage(); -echo $dat["ru_nswap"]; # number of swaps -echo $dat["ru_majflt"]; # number of page faults -echo $dat["ru_utime.tv_sec"]; # user time used (seconds) -echo $dat["ru_utime.tv_usec"]; # user time used (microseconds) - </programlisting> - </example> - Siehe auch im Handbuch des Betriebssystems für weitere Details. - </para> - </refsect1> - </refentry> - - <refentry id="function.phpinfo"> - <refnamediv> - <refname>phpinfo</refname> - <refpurpose>Zeigt viele Informationen zu PHP</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>phpinfo</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <para> - Zeigt eine grosse Anzahl von Informationen über die aktuelle - Konfiguration von PHP an. Unter anderem die Optionen während der - Kompilierens und die Erweiterungen, die PHP Version, - Informationen über den Server, die Umgebung (wenn PHP als Modul - kompiliert wurde), die PHP Umgebung, Version und Informationen - zum Betriebssystem, Pfade, Haupt- and lokale Werte der - Konfigurationsoptionen, HTTP Header, und die GNU Public - License. - </para> - <para> - Siehe auch <function>phpversion</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.php-logo-guid"> - <refnamediv> - <refname>php_logo_guid</refname> - <refpurpose>Die logo guid erhalten</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>php_logo_guid</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <para> - <note> - <para> - Diese Funktion wurde mit Version PHP4 Beta 4 eingeführt. - </para> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.php-sapi-name"> - <refnamediv> - <refname>php_sapi_name</refname> - <refpurpose> - Zeigt die Schnittstelle zwischen Webserver und PHP an - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>php_sapi_name</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - <function>php_sapi_name</function> zeigt die Schnittstelle zwischen Webserver und PHP - (Server API, SAPI) als kleingeschriebene Zeichenkette an. Bei CGI PHP ist diese Zeichenkette "cgi", bei - mod_php für Apache ist die Zeichenkette "apache" usw. - </simpara> - <para> - <example> - <title><function>php_sapi_name</function> Beispiel</title> - <programlisting role="php"> -$inter_type = php_sapi_name(); -if ($inter_type == "cgi") - print "Sie benutzen CGI PHP\n"; -else - print "Sie benutzen nicht CGI PHP\n"; - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.phpversion"> - <refnamediv> - <refname>phpversion</refname> - <refpurpose> - Zeigt die aktuell installierte PHP-Version - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>phpversion</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <para> - Zeigt die Version des installierten PHP-Parsers. - <example role="php"> - <title><function>phpversion</function> Beispiel</title> - <programlisting> -// Gibt z.B. 'Aktuelle PHP Version: 3.0rel-dev' aus -echo "Aktuelle PHP Version: ".phpversion(); - </programlisting> - </example> - </para> - <para> - Siehe auch <function>phpinfo</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.putenv"> - <refnamediv> - <refname>putenv</refname> - <refpurpose> - Setzt den Wert einer Umgebungsvariablen. - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>putenv</function></funcdef> - <paramdef>string <parameter>setting</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Setzt <parameter>setting</parameter> als Umgebungsvariable. - </para> - <para> - <example> - <title>Setzen einer Umgebungsvariablen</title> - <programlisting role="php"> -putenv ("UNIQID=$uniqid"); - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.set-magic-quotes-runtime"> - <refnamediv> - <refname>set_magic_quotes_runtime</refname> - <refpurpose>Setzt magic_quotes_runtime</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>long <function>set_magic_quotes_runtime</function></funcdef> - <paramdef>int <parameter>new_setting</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Setzt <link - linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>. - (0 für aus, 1 für an). - </simpara> - <simpara> - Siehe auch <function>get_magic_quotes_gpc</function> und - <function>get_magic_quotes_runtime</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.set-time-limit"> - <refnamediv> - <refname>set_time_limit</refname> - <refpurpose>Setzt die maximale Ausführungszeit</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>set_time_limit</function></funcdef> - <paramdef>int <parameter>seconds</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Legt die Zeit in Sekunden fest, die ein Script laufen darf. Ist - diese Zeit abgelaufen, wird ein Fehler zurückgegeben. Der - Standard liegt bei 30 Sekunden, es sei denn, max_execution_time - ist <link linkend="configuration.file">configuration file</link> - eingetragen. Bei einer Einstellung von 0 Sekunden ist die - maximale Ausführungszeit nicht begrenzt. - </simpara> - <simpara> + <reference id="ref.info"> + <title>PHP Optionen und Informationen</title> + <titleabbrev>PHP Optionen/Informationen</titleabbrev> + + <refentry id="function.extension-loaded"> + <refnamediv> + <refname>extension_loaded</refname> + <refpurpose>Zeigt an, ob eine Bibliothek geladen wurde</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>extension_loaded</function></funcdef> + <paramdef>string <parameter>name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Ist wahr, wenn die Bibliothek, die mit + <parameter>name</parameter> definiert wurde, geladen ist. Einen + Überblick über die verschiedenen Bibliotheken erhält mal mit + <function>phpinfo</function>. + </simpara> + <para> + Siehe auch <function>phpinfo</function>. + <note> + <para> + Diese Funktion wurde mit Version 3.0.10 eingeführt. + </para> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.getenv"> + <refnamediv> + <refname>getenv</refname> + <refpurpose>Zeigt den Wert einer Umgebungsvariablen an</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>getenv</function></funcdef> + <paramdef>string <parameter>varname</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Zeigt den Wert der Umgebungsvariablen + <parameter>varname</parameter> an oder &false; bei einem Fehler. + <informalexample> + <programlisting role="php"> +$ip = getenv ("REMOTE_ADDR"); // get the ip number of the user + </programlisting> + </informalexample> + </para> + <para> + Eine Liste aller Umgebungsvariablen wird mit + <function>phpinfo</function> angezeigt. Ein Überlick über viele + Umgebungsvariablen und deren Bedeutung findet sich unter den + <ulink url="&url.cgispecs;">CGI Spezificationen</ulink>, speziell + auf der Seite der <ulink url="&url.cgispec;">Umgebungsvariablen + </ulink>. + </para> + </refsect1> + </refentry> + + <refentry id="function.get-cfg-var"> + <refnamediv> + <refname>get_cfg_var</refname> + <refpurpose> + Zeigt den Wert einer Option der PHP-Konfiguration + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>get_cfg_var</function></funcdef> + <paramdef>string <parameter>varname</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Zeigt den derzeitigen Wert der Variablen der PHP-Konfiguration, + die mit <parameter>varname</parameter> ausgewählt wurde oder + &false; bei einem Fehler. + </simpara> + <simpara> + Bringt keine Informationen über die Konfiguration, mit der PHP + kompilert wurde, oder die aus der Apache-Konfiguration gelesen + wird (mittels der php3_configuration_option Anweisungen). + </simpara> + <simpara> + Um herauszubekommen, ob ein <link + linkend="configuration.file">configuration file</link>, benutzt + wird, sollte versucht werden, den Wert der cfg_file_path + Einstellung zu erhalten. Ist dieser Wert verfügbar, wird eine + Konfigurationsdatei verwendet. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.get-current-user"> + <refnamediv> + <refname>get_current_user</refname> + <refpurpose> + Den Besitzer des aktuellen PHP-Scripts anzeigen. + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>get_current_user</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Zeigt den Namen des Besitzers des aktuellen PHP-Scripts an. + </simpara> + <simpara> + Siehe auch <function>getmyuid</function>, + <function>getmypid</function>, <function>getmyinode</function>, + und <function>getlastmod</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.get-magic-quotes-gpc"> + <refnamediv> + <refname>get_magic_quotes_gpc</refname> + <refpurpose> + Zeigt die aktuelle Konfiguration von magic quotes gpc + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>long <function>get_magic_quotes_gpc</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Zeigt die aktuelle Konfiguration von + <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>. + (0 für aus, 1 für an). + </simpara> + <simpara> + Siehe auch <function>get_magic_quotes_runtime</function> und + <function>set_magic_quotes_runtime</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.get-magic-quotes-runtime"> + <refnamediv> + <refname>get_magic_quotes_runtime</refname> + <refpurpose> + Zeigt die aktuelle Konfiguration von magic_quotes_runtime + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef> + Long <function>get_magic_quotes_runtime</function> + </funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Zeigt die aktuelle Konfiguration von + <link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>. + (0 für aus, 1 für an). + </simpara> + <simpara> + Siehe auch <function>get_magic_quotes_gpc</function> und + <function>set_magic_quotes_runtime</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.getlastmod"> + <refnamediv> + <refname>getlastmod</refname> + <refpurpose> + Zeigt die Uhrzeit der letzten Änderung einer Seite + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>getlastmod</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <para> + Zeigt die Uhrzeit der letzten Änderung der aktuellen Seite. Der + Wert wird als Unix-Timestamp angezeigt, welcher für + <function>date</function> benutzt werden kann. Bringt &false; bei + einem Fehler. + <example> + <title><function>getlastmod</function> Beispiel</title> + <programlisting role="php"> +// outputs e.g. 'Last modified: March 04 1998 20:43:59.' +echo "Last modified: ".date ("F d Y H:i:s.", getlastmod()); + </programlisting> + </example> + </para> + <para> + Siehe auch <function>date</function>, + <function>getmyuid</function>, + <function>get_current_user</function>, + <function>getmyinode</function> und + <function>getmypid</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.getmyinode"> + <refnamediv> + <refname>getmyinode</refname> + <refpurpose>Gibt den Inode des aktuellen Skripts aus</refpurpose> + </refnamediv> + <refsect1> + <title>Beispiel</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>getmyinode</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <para> + Zeigt den inode des aktuellen Scripts oder &false; bei einem Fehler. + </para> + <para> + Siehe auch <function>getmyuid</function>, + <function>get_current_user</function>, + <function>getmypid</function> und + <function>getlastmod</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.getmypid"> + <refnamediv> + <refname>getmypid</refname> + <refpurpose>Zeigt die ID des PHP-Prozesses</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>getmypid</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <para> + Zeigt die aktuelle ID des PHP-Prozesses oder &false; bei einem + Fehler. + </para> + <para> + Achtung: Wenn PHP als Server-Modul läuft, ist es nicht + garantiert, dass Scripts unter verschiedenen PIDs laufen. + </para> + <para> + Siehe auch <function>getmyuid</function>, + <function>get_current_user</function>, + <function>getmyinode</function> und + <function>getlastmod</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.getmyuid"> + <refnamediv> + <refname>getmyuid</refname> + <refpurpose> + Zeigt die UID des Besitzers eines PHP-Scripts + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>getmyuid</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Zeigt die User-ID des aktuellen Scripts oder &false; bei einem + Fehler. + </simpara> + <simpara> + Siehe auch <function>getmypid</function>, + <function>get_current_user</function>, + <function>getmyinode</function> und + <function>getlastmod</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.getrusage"> + <refnamediv> + <refname>getrusage</refname> + <refpurpose> + Zeigt den aktuellen Ressourcenverbrauch an + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>getrusage</function></funcdef> + <paramdef>int <parameter><optional>who</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Dies ist eine Schnittstlle zu getrusage(2). Stellt ein + assoziatives Array mit den Daten zur Verfügung, die der + Systemaufruf ausgibt. Wenn who 1 ist, wird getusage mit + RUSAGE_CHILDREN aufgerufen. + </para> + <para> + Alle Einträge können über ihre Dukumentenfeldernamen aufgerufen + werden. + <example> + <title><function>getrusage</function> Beispiel</title> + <programlisting role="php"> +$dat = getrusage(); +echo $dat["ru_nswap"]; # number of swaps +echo $dat["ru_majflt"]; # number of page faults +echo $dat["ru_utime.tv_sec"]; # user time used (seconds) +echo $dat["ru_utime.tv_usec"]; # user time used (microseconds) + </programlisting> + </example> + Siehe auch im Handbuch des Betriebssystems für weitere Details. + </para> + </refsect1> + </refentry> + + <refentry id="function.phpinfo"> + <refnamediv> + <refname>phpinfo</refname> + <refpurpose>Zeigt viele Informationen zu PHP</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>phpinfo</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <para> + Zeigt eine grosse Anzahl von Informationen über die aktuelle + Konfiguration von PHP an. Unter anderem die Optionen während der + Kompilierens und die Erweiterungen, die PHP Version, + Informationen über den Server, die Umgebung (wenn PHP als Modul + kompiliert wurde), die PHP Umgebung, Version und Informationen + zum Betriebssystem, Pfade, Haupt- and lokale Werte der + Konfigurationsoptionen, HTTP Header, und die GNU Public + License. + </para> + <para> + Siehe auch <function>phpversion</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.php-logo-guid"> + <refnamediv> + <refname>php_logo_guid</refname> + <refpurpose>Die logo guid erhalten</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>php_logo_guid</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <para> + <note> + <para> + Diese Funktion wurde mit Version PHP4 Beta 4 eingeführt. + </para> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.php-sapi-name"> + <refnamediv> + <refname>php_sapi_name</refname> + <refpurpose> + Zeigt die Schnittstelle zwischen Webserver und PHP an + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>php_sapi_name</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + <function>php_sapi_name</function> zeigt die Schnittstelle zwischen Webserver und PHP + (Server API, SAPI) als kleingeschriebene Zeichenkette an. Bei CGI PHP ist diese Zeichenkette "cgi", bei + mod_php für Apache ist die Zeichenkette "apache" usw. + </simpara> + <para> + <example> + <title><function>php_sapi_name</function> Beispiel</title> + <programlisting role="php"> +$inter_type = php_sapi_name(); +if ($inter_type == "cgi") + print "Sie benutzen CGI PHP\n"; +else + print "Sie benutzen nicht CGI PHP\n"; + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.phpversion"> + <refnamediv> + <refname>phpversion</refname> + <refpurpose> + Zeigt die aktuell installierte PHP-Version + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>phpversion</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <para> + Zeigt die Version des installierten PHP-Parsers. + <example role="php"> + <title><function>phpversion</function> Beispiel</title> + <programlisting> +// Gibt z.B. 'Aktuelle PHP Version: 3.0rel-dev' aus +echo "Aktuelle PHP Version: ".phpversion(); + </programlisting> + </example> + </para> + <para> + Siehe auch <function>phpinfo</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.putenv"> + <refnamediv> + <refname>putenv</refname> + <refpurpose> + Setzt den Wert einer Umgebungsvariablen. + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>putenv</function></funcdef> + <paramdef>string <parameter>setting</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Setzt <parameter>setting</parameter> als Umgebungsvariable. + </para> + <para> + <example> + <title>Setzen einer Umgebungsvariablen</title> + <programlisting role="php"> +putenv ("UNIQID=$uniqid"); + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.set-magic-quotes-runtime"> + <refnamediv> + <refname>set_magic_quotes_runtime</refname> + <refpurpose>Setzt magic_quotes_runtime</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>long <function>set_magic_quotes_runtime</function></funcdef> + <paramdef>int <parameter>new_setting</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Setzt <link + linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>. + (0 für aus, 1 für an). + </simpara> + <simpara> + Siehe auch <function>get_magic_quotes_gpc</function> und + <function>get_magic_quotes_runtime</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.set-time-limit"> + <refnamediv> + <refname>set_time_limit</refname> + <refpurpose>Setzt die maximale Ausführungszeit</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>set_time_limit</function></funcdef> + <paramdef>int <parameter>seconds</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Legt die Zeit in Sekunden fest, die ein Script laufen darf. Ist + diese Zeit abgelaufen, wird ein Fehler zurückgegeben. Der + Standard liegt bei 30 Sekunden, es sei denn, max_execution_time + ist <link linkend="configuration.file">configuration file</link> + eingetragen. Bei einer Einstellung von 0 Sekunden ist die + maximale Ausführungszeit nicht begrenzt. + </simpara> + <simpara> Wenn <function>set_time_limit</function> aufgerufen wird, dann startet der Zähler neu. Das heisst, wenn die Standardeinstellung 30 Sekunden beträgt und nach 25 Sekunden durch ein Script ein Aufruf wie z.B. <literal>set_time_limit(20)</literal> erfolgt, darf das Script insgesamt 45 Sekunden laufen, bevor eine Fehlermeldung ausgegeben wird. - </simpara> - <simpara> - Achtung: Wenn PHP im Safemode läuft, hat - <function>set_time_limit</function> keinen Effekt. Die einzige - Möglichkeit, dies zu umgehen, ist den Safemode im <link - linkend="configuration.file">configuration file</link> - auszuschalten. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.zend-logo-guid"> - <refnamediv> - <refname>zend_logo_guid</refname> - <refpurpose>Zeigt die Zend guid</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>zend_logo_guid</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - <para> - <note> - <para> - Diese Funktion wurde mit Version PHP4 Beta 4 eingeführt. - </para> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.get-loaded-extensions"> - <refnamediv> - <refname>get_loaded_extensions</refname> - <refpurpose> - Stellt ein Array mit den Namen aller Module, die kompiliert und geladen sind, zur - Verfügung - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>get_loaded_extensions</function></funcdef> - <paramdef>void </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Dieser Funktion zeigt die Namen aller Module an, die in den PHP-Interpreter - kompiliert und geladen wurden - </para> - <para> - Zum Beispiel gibt diese Zeile - <informalexample> - <programlisting> -print_r(get_loaded_extensions()); - </programlisting> - </informalexample> - eine Liste wie die folgende aus: - <informalexample> - <programlisting> -Array -( - [0] =&gt; xml - [1] =&gt; wddx - [2] =&gt; standard - [3] =&gt; session - [4] =&gt; posix - [5] =&gt; pgsql - [6] =&gt; pcre - [7] =&gt; gd - [8] =&gt; ftp - [9] =&gt; db - [10] =&gt; Calendar - [11] =&gt; bcmath -) - </programlisting> - </informalexample> - </para> - <para> - Siehe auch: <function>get_extension_funcs</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.get-extension-funcs"> - <refnamediv> - <refname>get_extension_funcs</refname> - <refpurpose> - Stellt ein Array mit den Namen einer Funktion eines Moduls zur Verfügung - </refpurpose> - </refnamediv> - <refsect1> - <title>Bescheibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>get_extension_funcs</function></funcdef> - <paramdef>string <parameter>module_name</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Diese Funktion zeigt die Namen aller Funktionen, die im - Modul, welches von <parameter>module_name</parameter> angezeigt wird, an. - </para> - <para> - Zum Beispiel würden diese Zeilen - <informalexample> - <programlisting> -print_r(get_extension_funcs(&quot;xml&quot;)); -print_r(get_extension_funcs(&quot;gd&quot;)); - </programlisting> - </informalexample> - eine Liste von Funktionen in den Modulen <varname>xml</varname> - bzw. <varname>gd</varname> ausgeben. - </para> - <para> - Siehe auch: <function>get_loaded_extensions</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.get-required-files"> - <refnamediv> - <refname>get_required_files</refname> - <refpurpose> - Stellt ein Array mit den Namen der Dateien zur Verfügung, die über require_once() in einem Script aufgerufen wurden - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>get_required_files</function></funcdef> - <paramdef>void </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Diese Funktion stellt ein assoziatives Array der Namen aller Dateien zur Verfügung, - die mit <function>require_once</function> in ein Script geladen wurden. Die Indexe dieses Arrays sind - die Dateinamen, die in <function>require_once</function> benutzt werden, ohne die Endung - &quot;.php&quot;. - </para> - <para> - Dieses Beispiel - <example> - <title>Ausgabe der required und included Dateien</title> - <programlisting> -&lt;?php - -require_once(&quot;local.php&quot;); -require_once(&quot;../inc/global.php&quot;); - -for ($i=1; $i&lt;5; $i++) - include &quot;util&quot;.$i.&quot;php&quot;; - -echo &quot;Required_once files\n&quot;; -print_r(get_required_files()); - -echo &quot;Included_once files\n&quot;; -print_r(get_included_files()); - </programlisting> - </example> - wird folgendes ausgeben: - <informalexample> - <programlisting> -Required_once files -Array -( - [local] =&gt; local.php - [../inc/global] =&gt; /full/path/to/inc/global.php -) - -Included_once files -Array -( - [util1] =&gt; util1.php - [util2] =&gt; util2.php - [util3] =&gt; util3.php - [util4] =&gt; util4.php -) - </programlisting> - </informalexample> - </para> - <para> - <note> - <para> - Ab PHP 4.0.1pl2 setzt diese Funktion vorraus, daß die Dateien, die mit - <varname>required_once</varname> aufgerufen wurden, die Endung - &quot;.php&quot; haben. Andere Endungen funktionieren nicht. - </para> - </note> - </para> - <para> - Siehe auch: <function>require_once</function>, - <function>include_once</function>, - <function>get_included_files</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.get-included-files"> - <refnamediv> - <refname>get_included_files</refname> - <refpurpose> - Stellt ein Array der Dateinamen zur Verfügung, die mittels include_once() in ein Script geladen wurden - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>get_included_files</function></funcdef> - <paramdef>void </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Diese Funktion stellt ein assoziatives Array der Namen aller Dateien zur Verfügung, - die mit <function>include_once</function> in ein Script geladen wurden. Die Indexe dieses Arrays sind - die Dateinamen, die in <function>include_once</function> benutzt wurden, ohne die Endung - &quot;.php&quot;. - </para> - <para> - <note> - <para> - Ab PHP 4.0.1pl2 setzt diese Funktion vorraus, daß die Dateien, die mit - <varname>include_once</varname>aufgerufen wurden, die Endung - &quot;.php&quot; haben. Andere Endungen funktionieren nicht. - </para> - </note> - </para> - <para> - Siehe auch: <function>require_once</function>, - <function>include_once</function>, - <function>get_required_files</function> - </para> - </refsect1> - </refentry> - - </reference> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> + </simpara> + <simpara> + Achtung: Wenn PHP im Safemode läuft, hat + <function>set_time_limit</function> keinen Effekt. Die einzige + Möglichkeit, dies zu umgehen, ist den Safemode im <link + linkend="configuration.file">configuration file</link> + auszuschalten. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.zend-logo-guid"> + <refnamediv> + <refname>zend_logo_guid</refname> + <refpurpose>Zeigt die Zend guid</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>zend_logo_guid</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + <para> + <note> + <para> + Diese Funktion wurde mit Version PHP4 Beta 4 eingeführt. + </para> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.get-loaded-extensions"> + <refnamediv> + <refname>get_loaded_extensions</refname> + <refpurpose> + Stellt ein Array mit den Namen aller Module, die kompiliert und geladen sind, zur + Verfügung + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>get_loaded_extensions</function></funcdef> + <paramdef>void </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Dieser Funktion zeigt die Namen aller Module an, die in den PHP-Interpreter + kompiliert und geladen wurden + </para> + <para> + Zum Beispiel gibt diese Zeile + <informalexample> + <programlisting> +print_r(get_loaded_extensions()); + </programlisting> + </informalexample> + eine Liste wie die folgende aus: + <informalexample> + <programlisting> +Array +( + [0] =&gt; xml + [1] =&gt; wddx + [2] =&gt; standard + [3] =&gt; session + [4] =&gt; posix + [5] =&gt; pgsql + [6] =&gt; pcre + [7] =&gt; gd + [8] =&gt; ftp + [9] =&gt; db + [10] =&gt; Calendar + [11] =&gt; bcmath +) + </programlisting> + </informalexample> + </para> + <para> + Siehe auch: <function>get_extension_funcs</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.get-extension-funcs"> + <refnamediv> + <refname>get_extension_funcs</refname> + <refpurpose> + Stellt ein Array mit den Namen einer Funktion eines Moduls zur Verfügung + </refpurpose> + </refnamediv> + <refsect1> + <title>Bescheibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>get_extension_funcs</function></funcdef> + <paramdef>string <parameter>module_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Diese Funktion zeigt die Namen aller Funktionen, die im + Modul, welches von <parameter>module_name</parameter> angezeigt wird, an. + </para> + <para> + Zum Beispiel würden diese Zeilen + <informalexample> + <programlisting> +print_r(get_extension_funcs(&quot;xml&quot;)); +print_r(get_extension_funcs(&quot;gd&quot;)); + </programlisting> + </informalexample> + eine Liste von Funktionen in den Modulen <varname>xml</varname> + bzw. <varname>gd</varname> ausgeben. + </para> + <para> + Siehe auch: <function>get_loaded_extensions</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.get-required-files"> + <refnamediv> + <refname>get_required_files</refname> + <refpurpose> + Stellt ein Array mit den Namen der Dateien zur Verfügung, die über require_once() in einem Script aufgerufen wurden + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>get_required_files</function></funcdef> + <paramdef>void </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Diese Funktion stellt ein assoziatives Array der Namen aller Dateien zur Verfügung, + die mit <function>require_once</function> in ein Script geladen wurden. Die Indexe dieses Arrays sind + die Dateinamen, die in <function>require_once</function> benutzt werden, ohne die Endung + &quot;.php&quot;. + </para> + <para> + Dieses Beispiel + <example> + <title>Ausgabe der required und included Dateien</title> + <programlisting> +&lt;?php + +require_once(&quot;local.php&quot;); +require_once(&quot;../inc/global.php&quot;); + +for ($i=1; $i&lt;5; $i++) + include &quot;util&quot;.$i.&quot;php&quot;; + +echo &quot;Required_once files\n&quot;; +print_r(get_required_files()); + +echo &quot;Included_once files\n&quot;; +print_r(get_included_files()); + </programlisting> + </example> + wird folgendes ausgeben: + <informalexample> + <programlisting> +Required_once files +Array +( + [local] =&gt; local.php + [../inc/global] =&gt; /full/path/to/inc/global.php +) + +Included_once files +Array +( + [util1] =&gt; util1.php + [util2] =&gt; util2.php + [util3] =&gt; util3.php + [util4] =&gt; util4.php +) + </programlisting> + </informalexample> + </para> + <para> + <note> + <para> + Ab PHP 4.0.1pl2 setzt diese Funktion vorraus, daß die Dateien, die mit + <varname>required_once</varname> aufgerufen wurden, die Endung + &quot;.php&quot; haben. Andere Endungen funktionieren nicht. + </para> + </note> + </para> + <para> + Siehe auch: <function>require_once</function>, + <function>include_once</function>, + <function>get_included_files</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.get-included-files"> + <refnamediv> + <refname>get_included_files</refname> + <refpurpose> + Stellt ein Array der Dateinamen zur Verfügung, die mittels include_once() in ein Script geladen wurden + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>get_included_files</function></funcdef> + <paramdef>void </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Diese Funktion stellt ein assoziatives Array der Namen aller Dateien zur Verfügung, + die mit <function>include_once</function> in ein Script geladen wurden. Die Indexe dieses Arrays sind + die Dateinamen, die in <function>include_once</function> benutzt wurden, ohne die Endung + &quot;.php&quot;. + </para> + <para> + <note> + <para> + Ab PHP 4.0.1pl2 setzt diese Funktion vorraus, daß die Dateien, die mit + <varname>include_once</varname>aufgerufen wurden, die Endung + &quot;.php&quot; haben. Andere Endungen funktionieren nicht. + </para> + </note> + </para> + <para> + Siehe auch: <function>require_once</function>, + <function>include_once</function>, + <function>get_required_files</function> + </para> + </refsect1> + </refentry> + + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/de/functions/ldap.xml diff -u phpdoc/de/functions/ldap.xml:1.9 phpdoc/de/functions/ldap.xml:1.10 --- phpdoc/de/functions/ldap.xml:1.9 Sat Jul 7 18:16:59 2001 +++ phpdoc/de/functions/ldap.xml Sat Jul 7 19:11:20 2001 @@ -1,2031 +1,2031 @@ -<reference id="ref.ldap"> -<title>LDAP Funktionen</title> -<titleabbrev>LDAP</titleabbrev> - -<partintro> -<sect1 id="ldap.intro"> -<title>Einführung zu LDAP</title> - <para> - LDAP steht für Lightweight Directory Access Protocol und ist - ein Protokoll um auf "Directory Servers" - "Verzeichnis- - Server" - zuzugreifen. - Das Verzeichnis ist dabei eine spezielle Art einer Datenbank, - das Informationen in einer Baumstruktur bereithält. - </para> - <para> - Das Konzept ist dabei ähnlich der Verzeichnisstruktur Ihrer - Festplatte, mit der Ausnahme, daß in diesem Zusammenhang - das Wurzelverzeichnis "Die Welt" ist und die - Unterverzeichnisse der ersten Ebene "Länder" abbilden. - Die weiteren Verzeichnisse unterhalb der Länderebene enthalten - Einträge für Firmen, Organisationen oder Städte. Noch tiefer - geschachtelt stehen Verzeichniseinträge für Menschen und - vielleicht für Ausstattung oder Dokumente. - </para> - <para> - Um auf eine Datei in einem Unterverzeichnis auf Ihrer - Festplatte zu verweisen, könnten Sie eine Schreibweise wie - folgt verwenden - </para> - <literallayout> - /usr/local/meine_daten/doku - </literallayout> - <para> - Die Schrägstriche markieren jeden Teil in diesem Verweis und - die Sequenz wird von links nach rechts gelesen. - </para> - <para> - Das entsprechende Gegenstück zu einer voll qualifizierten - Dateireferenz ist in LDAP der "Eindeutige Name" - ("distinguished name"), der Einfachheit halber als "dn" - bezeichnet. - Ein Beispiel für einen solchen dn könnte sein - </para> - <literallayout> - cn=Hans Mustermann,ou=Buchhaltung,o=Meine Firma,c=DE - </literallayout> - <para> - Das Komma markiert jeden Teil in diesem Verweis und die - Sequenz wird von rechts nach links gelesen. - Diesen dn würden Sie wie folgt lesen ... - </para> - <literallayout> - Land = DE - Organisation (organisation) = Meine Firma - Organisationseinheit (organisational unit) = Buchhaltung - Einfacher Name (commonName) = Hans Mustermann - </literallayout> - <para> - In der gleichen Weise, in der es keine allgemeinverbindlichen - Regeln gibt, wie Sie die Verzeichnisstruktur Ihrer Festplatte - organsieren, kann der Verwalter eines Verzeichnis-Servers jede - beliebige Struktur implementieren, die für den Einsatzzweck - sinnvoll ist. - Trotzdem gibt es einige Konventionen die benutzt werden. - Die Botschaft ist folgende: Sie können keinen Code schreiben - um auf einen Verzeichnis-Server zuzugreifen, ohne etwas über - dessen Struktur zu wissen. Genauso wenig können Sie eine - Datenbank nutzen ohne Kenntnis darüber, was in derselben - vorhanden ist. - </para> -</sect1> - -<sect1 id="ldap-example"> -<title>Komplettes Code Beispiel</title> - <para> - Informationen von einem Verzeichnis-Server beziehen für alle - Einträge bei denen der Nachname mit "S" beginnt. Darstellung - eines Auszugs mit Name und Email-Adresse. - </para> - - <example> - <title>LDAP Such-Beispiel</title> - <programlisting role="php"> - &lt;?php - // Grundlegende Abfolge bei LDAP ist verbinden, binden, suchen, - // interpretieren des Sucheergebnisses, Verbindung schließen - - echo "&lt;h3>LDAP query Test&lt;/h3>"; - echo "Verbindung ..."; - $ds=ldap_connect("localhost"); // muss ein gültiger LDAP Server - // sein! - - echo "Ergebnis der Verbindung: ".$ds."&lt;p>"; - - if ($ds) { - echo "Bindung ..."; - $r=ldap_bind($ds); // das ist ein "anonymer" bind, - // typischerweise nur Lese Zugriff - echo "Ergebnis der Bindung ".$r."&lt;p>"; - - echo "Suche nach (sn=S*) ..."; - // Suchen des Nachnamen-Eintrags - $sr=ldap_search($ds,"o=Meine Firma, c=DE", "sn=S*"); - echo "Ergebnis der Suche ".$sr."&lt;p>"; - - echo "Anzahl der Einträge, die gefunden wurden - .ldap_count_entries($ds,$sr)."&lt;p>"; - - echo "Einträge holen ...&lt;p>"; - $info = ldap_get_entries($ds, $sr); - echo "Daten für ".$info["count"]." Items gefunden:&lt;p>"; - - for ($i=0; $i&lt;$info["count"]; $i++) { - echo "dn ist: ". $info[$i]["dn"] ."&lt;br>"; - echo "erster cn Eintrag: ". $info[$i]["cn"][0] ."&lt;br>"; - echo "erster email Eintrag: ". $info[$i]["mail"][0] - ."&lt;p>"; - } - - echo "Verbindung schließen"; - ldap_close($ds); - - } else { - echo "&lt;h4>Verbindung zu LDAP Server nicht möglich&lt;/h4>"; - } - ?> - </programlisting> - </example> - -<sect2 id="ldap.using"> -<title>Verwenden der PHP LDAP Aufrufe</title> - <para> - Sie müssen sich die LDAP Client Bibliotheken herunterladen und - übersetzen. Sie können entweder das ldap-3.3 Packet von der - University of Michigan oder das Netscape Directory SDK 3.0 - verwenden. Ebenso müssen Sie Ihr PHP mit LDAP Unterstützung - aktiviert neu übersetzen bevor die PHP LDAP-Aufrufe - funktionieren. - </para> - <para> - Bevor Sie die LDAP Aufrufe benutzen können, müssen Sie folgendes - wissen... - <itemizedlist> - <listitem> - <para> - Den Namen oder die Adresse des Verzeichnis-Servers den Sie - benutzen wollen - </para> - </listitem> - <listitem> - <para> - Den "Basis dn" des Servers (den Teil des Weltverzeichnisses, - das auf diesem Server eingerichtet ist, das könnte "o=Meine - Firma,c=DE" sein. - </para> - </listitem> - <listitem> - <para> - Brauchen Sie ein Passwort um auf den Server zuzugreifen? - (Viele Server bieten Lesezugriff für einen "anonymen bind", - verlangen aber ein Passwort für alles weitere) - </para> - </listitem> - </itemizedlist> - </para> - <para> - Die typische Abfolge von LDAP Aufrufen in einer Anwendung folgen - diesem Muster - <literallayout> - ldap_connect() // Aufbau einer Verbindung zum Server - - connection to server - | - ldap_bind() // anonymes oder authentifiziertes "login" - | - mache irgendwas, z.B. Verzeichnis durchsuchen oder aktualisieren - und stelle das Ergebnis dar - | - ldap_close() // "logout" -</literallayout></para> - -</sect2> -<sect2 id="ldap.moreinfo"> -<title>Mehr Informationen</title> - <para> - Viele Informationen finden Sie unter - </para> - - <itemizedlist> - <listitem> - <para> - <ulink url="&url.ldap.netscape;">Netscape</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="&url.ldap.michigan;">University of Michigan</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="&url.ldap.openldap;">OpenLDAP Project</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="&url.ldap.ldapworld;">LDAP World</ulink> - </para> - </listitem> - </itemizedlist> - - <para> - Das Netscape SDK enthält einen hilfreichen Programmer´s Guide im - .html Format. - </para> -</sect2> -</sect1> - -</partintro> - - -<refentry id="function.ldap-add"> -<refnamediv> - <refname>ldap_add</refname> - <refpurpose> - Einträge einem LDAP Verzeichnis hinzufügen - </refpurpose> -</refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_add</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>array <parameter>eintrag</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_add</function> Funktion wird benutzt um - Einträge einem Verzeichnis hinzuzufügen. Die DN des Eintrags, der - hinzugefügt werden soll wird durch dn bestimmt. Array eintrag - bestimmt die Informationen des Eintrags. Die Werte in den - Einträgen werden durch individuelle Merkmale indiziert. - Im Fall von mehreren Werten für ein Merkmal werden diese durch - die Verwendung von Zahlen indiziert, die bei 0 beginnen. - </para> - <informalexample> -<literallayout> - eintrag["merkmal1"] = wert - eintrag["merkmal2"][0] = wert1 - eintrag["merkmal2"][1] = wert2 -</literallayout> - </informalexample> - <example> - <title>Komplettes Beispiel mit authentifiziertem bind</title> - -<programlisting role="php"> -&lt;?php -$ds=ldap_connect("localhost"); // Annahme: der LDAP Server befindet - // sich auf diesem Host - -if ($ds) { - // bind mit passendem dn für aktulisierenden Zugriff - $r=ldap_bind($ds,"cn=root, o=Meine Firma, c=DE", "geheim"); - - // Daten vorbereiten - $info["cn"]="Hans Mustermann"; - $info["sn"]="Mustermann"; - $info["mail"]="MustermannH@firma.de"; - $info["objectclass"]="person"; - - // hinzufügen der Daten zum Verzeichnis - $r=ldap_add($ds, "cn=Hans Mustermann, o=Meine Firma, c=DE", - $info); - - ldap_close($ds); -} else { - echo "Verbindung zum LDAP Server nicht möglich!"; -} -?> -</programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.ldap-bind"> - <refnamediv> - <refname>ldap_bind</refname> - <refpurpose>Bindung zu einem LDAP Verzeichnis</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_bind</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter><optional>bind_rdn</optional> - </parameter></paramdef> - <paramdef>string <parameter><optional>bind_kennwort</optional> - </parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Bindung für ein LDAP Verzeichnis mit angegebenem RDN und - Kennwort. Rückgabewert: wahr im Erfolgsfall, falsch im - Fehlerfall. - </para> - <para> - Die <function>ldap_bind</function> Funktion führt eine bind - Operation auf einem Verzeichnis aus. bind_rdn und bind_kennwort - sind optional, wenn diese fehlen wird ein anonymes bind versucht. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-close"> - <refnamediv> - <refname>ldap_close</refname> - <refpurpose>Verbindung zum LDAP Server schliessen</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_close</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_close</function> Funktion schließt die - Verbindung zum LDAP Server die zur - <parameter>Verbindungs-Kennung</parameter> gehört. - </para> - <para> - Der Aufruf dieser Funktion ist intern identisch zu - <function>ldap_unbind</function>. Die LDAP API benutzt den Aufruf - <function>ldap_unbind</function>, so dass Sie vielleicht diese - Funktion benutzen sollten, anstatt<function> - ldap_close</function> zu verwenden.</para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-compare"> - <refnamediv> - <refname>ldap_compare</refname> - <refpurpose> - Vergleicht gefundenen Wert eines Merkmal in einem Eintrag, der - durch Angabe von dn destimmt wird. - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_compare</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>string <parameter>merkmal</parameter></paramdef> - <paramdef>string <parameter>wert</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Rückgabewert: wahr, wenn <parameter>wert</parameter> gefunden - wird, ansonsten falsch. Tritt ein Fehler auf, wird -1 - zurückgegeben. - </simpara> - <para> - <function>ldap_compare</function> vergleicht den<parameter> - wert</parameter> eines <parameter>merkmal</parameter> mit dem - Wert des gleichen Merkmals in dem LDAP Verzeichniseintrag der - durch <parameter>dn</parameter> bestimmt wurde. - </para> - <simpara> - Das folgende Beispiel zeigt, wie überprüft wird, ob ein gegebenes - Kennwort mit dem Kennwort übereinstimmt oder nicht, das in dem - durch DN bestimmten Eíntrag gespeichert ist. - </simpara> - <example> - <title>Komplettes Beispiel einer Kennwort-Überprüfung</title> - <programlisting role="php"> -&lt;?php - -$ds=ldap_connect("localhost"); // Annahme: der LDAP Server befindet - // sich auf diesem Host - -if ($ds) { - - // binden - if(ldap_bind($ds)) { - - // Daten vobereiten - $dn = "cn=Helga Olsen, ou=Meine Einheit, o=Meine Firma, c=FI"; - $value = "geheimeskennwort"; - $attr = "kennwort"; - - // vergleiche Werte - $r=ldap_compare($ds, $dn, $attr, $value); - - if ($r === -1) { - echo "Fehler: ".ldap_error($ds); - } elseif ($r === TRUE) { - echo "Kennwort korrekt."; - } elseif ($r === FALSE) { - echo "Falsch geraten! Kennwort nicht korrekt."; - } - - } else { - echo "Keine Bindung zum LDAP Server möglich."; - } - - ldap_close($ds); - -} else { - echo "Keine Verbindung zum LDAP Server möglich."; -} -?&gt; - - </programlisting> - </example> - <note> - <para> - <function>ldap_compare</function> kann NICHT für Vergleiche von - BINÄREN Werten benutzt werden! - </para> - </note> - <note> - <para> - Diese Funktion wurde in 4.0.2 hinzugefügt. - </para> - </note> - </refsect1> - </refentry> - - - <refentry id="function.ldap-connect"> - <refnamediv> - <refname>ldap_connect</refname> - <refpurpose>Verbindung zu einem LDAP Server</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_connect</function></funcdef> - <paramdef>string <parameter><optional>hostname</optional> - </parameter></paramdef> - <paramdef>int <parameter><optional>port</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: Eine positive Verbindungs-Kennung im Erfolgsfall, - falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_connect</function> Funktion öffnet eine - Verbindung zu einem LDAP Server auf einem bestimmten<parameter> - hostname</parameter> und <parameter>port</parameter>. Beide - Argumente sind optional. Wenn keine Argumente angegeben werden, - wird die Verbindungs-Kennung einer eventuell schon geöffneten - Verbindung zurückgeliefert. Wird nur der<parameter> - hostname</parameter> angegeben, wird für den Port der Standarport - 389 benutzt. - </para> - <para> - Bei Verwendung von OpenLDAP 2.x.x können Sie eine URL statt des - Hostnamens angeben. - Um LDAP mit SSL-Unterstützzung zu verwenden, übersetzen Sie - OpenLDAP mit SSL-Unterstützung, PHP mit SSL und verwenden - ldaps://Hostname/ als Host Argument. Das Port Argument wird bei - der Verwendung von URLs nicht benutzt. - URL und SSL Unterstützung wurden in 4.0.4 hinzugefügt</para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-count-entries"> - <refnamediv> - <refname>ldap_count_entries</refname> - <refpurpose>Zählt die Anzahl der Einträge bei einer - Suche</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_count_entries</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: Anzahl der Einträge im Ergebnis, falsch im - Fehlerfall.</para> - <para> - Die <function>ldap_count_entries</function> Funktion liefert die - Anzahl der Einträge im gespeicherten Ergebnis einer vorher - durchgeführten Suchoperation. - <parameter>Ergebnis-Kennung</parameter> bezeichnet das interne - LDAP Ergebnis. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-delete"> - <refnamediv> - <refname>ldap_delete</refname> - <refpurpose>Löscht einen Eintrag aus einem Verzeichnis - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_delete</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_delete</function> Funktion löscht einen - einzelnen Eintrag aus einem LDAP Verzeichnis, das im dn angegeben - wurde. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-dn2ufn"> - <refnamediv> - <refname>ldap_dn2ufn</refname> - <refpurpose> - Konvertiert DN in ein benutzerfreundliches Namensformat - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ldap_dn2ufn</function></funcdef> - <paramdef>string <parameter>dn</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Die <function>ldap_dn2ufn</function> Funktion wird verwendet um - einen DN in einer benutzerfreundlicheren Form darzustellen, wobei - die Typen-Namen wegfallen. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-err2str"> - <refnamediv> - <refname>ldap_err2str</refname> - <refpurpose> - Konvertiert eine LDAP Fehlernummer in einen Fehlertext - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ldap_err2str</function></funcdef> - <paramdef>int <parameter>Fehlernummer</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: Fehlertext.</para> - <para> - Diese Funktion liefert den Fehlertext der die Fehlernummer - erklärt. - Während LDAP Fehlernummern standardisiert sind, liefern - unterschiedliche Bibliotheken unterschiedliche oder sogar - lokalspezifische Fehlermeldungen. Deshalb sollten Sie nie auf - eine spezielle Fehlermeldung prüfen, sondern immer eine - Fehlernummer verwenden. - </para> - <para> - Siehe auch <function>ldap_errno</function> und - <function>ldap_error</function>. - - <example> - <title>Aufzählung aller LDAP Fehlermeldungen</title> -<programlisting role="php"> -&lt;?php - for($i=0; $i&lt;100; $i++) { - printf("Fehler $i: %s&lt;br>\n", ldap_err2str($i)); - } -?> -</programlisting> - </example> - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-errno"> - <refnamediv> - <refname>ldap_errno</refname> - <refpurpose> - Liefert die LDAP Fehlernummer des letzten LDAP Kommandos - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_errno</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: LDAP Fehlernummer des letzten LDAP Kommandos für - diese Verbindung. - </para> - <para> - Diese Funktion liefert die standardisierte Fehlernummer des - zuletzt ausgeführten LDAP Kommandos für die angegebene - Vebindungs-Kennung. Diese Nummer kann mit der Funktion <function> - ldap_err2str</function> in einen Fehlertext konvertiert werden. - </para> - <para> - Solange Sie die Stufe der Fehlerwarnungen in Ihrer php3.ini nicht - herabsetzen oder vor Ihre LDAP Komanndos ein @ (at) setzen - um die Ausgabe von Fehlermeldungen zu unterdrücken, werden die - aufgetretenen Fehler auch in Ihrer HTML Ausgabe zu sehen sein. - <example> - <title>Erzeugen und Abfangen eines Fehlers</title> -<programlisting role="php"> -&lt;?php -/* Diese Beispiel enhält einen Fehler, der abgefangen wird.*/ -$ld = ldap_connect("localhost"); -$bind = ldap_bind($ld); -// Syntax Fehler im Filterausdruck (errno 87), -// müsste "objectclass=*" heißen, um zu funktionieren. -$res = @ldap_search($ld, "o=Meine Firma, c=DE", "objectclass"); -if (!$res) { - printf("LDAP-Fehlernummer: %s&lt;br>\n", ldap_errno($ld)); - printf("LDAP-Fehler: %s&lt;br>\n", ldap_error($ld)); - die("Argh!&lt;br>\n"); -} -$info = ldap_get_entries($ld, $res); -printf("%d Übereinstimmende Einträge.&lt;br>\n", $info["count"]); -?> -</programlisting> - </example> - </para> - <para> - Siehe auch <function>ldap_err2str</function> und - <function>ldap_error</function>.</para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-error"> - <refnamediv> - <refname>ldap_error</refname> - <refpurpose> - Liefert die LDAP Fehlermeldung des letzten LDAP Kommandos - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ldap_error</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabe: Fehlertext</para> - <para> - Diese Funktion liefert den erklärenden Fehlertext für einen - Fehler, der vom zuletzt ausgeführten LDAP Kommando mit der - angegebenen Verbindungs-Kennung erzeugt wurde. - Während LDAP Fehlernummern standardisiert sind, liefern - unterschiedliche Bibliotheken unterschiedliche oder sogar - lokalspezifische Fehlermeldungen. Deshalb sollten Sie nie auf - eine spezielle Fehlermeldung prüfen, sondern immer eine - Fehlernummer verwenden. - </para> - <para> - Solange Sie die Stufe der Fehlerwarnungen in Ihrer php3.ini nicht - herabsetzen oder vor Ihre LDAP Komanndos ein @ (at) setzen - um die Ausgabe von Fehlermeldungen zu unterdrücken, werden die - aufgetretenen Fehler auch in Ihrer HTML Ausgabe zu sehen sein. - </para> - <para> - Siehe auch <function>ldap_err2str</function> und - <function>ldap_errno</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-explode-dn"> - <refnamediv> - <refname>ldap_explode_dn</refname> - <refpurpose> - Aufteilung eines DN in seine Bestandteile - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>ldap_explode_dn</function></funcdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>int <parameter>mit_merkmal</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Die <function>ldap_explode_dn</function> Funktion wird benutzt um - einen von <function>ldap_get_dn</function> gelieferten DN - aufzuteilen und in dessen Bestandteile zu zerlegen. Jeder Teil - wird als Relative Distinguished Name, RDN, bezeichnet. - <function>ldap_explode_dn</function> liefert einen Array mit - allen diesen Bestandteilen - Der Parameter <parameter>mit_merkmal</parameter> wird benutzt, um - zu bestimmen, ob die RDNs nur mit Werten oder zusätlich mit ihren - Merkmalen angefragt werden. Um RDNs mit Merkmalen (z.B. Merkmal= - Wert Format) zu erhalten, setzen Sie <parameter> - mit_merkmal</parameter> auf 0, um nur Werte zu erhalten auf 1. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-first-attribute"> - <refnamediv> - <refname>ldap_first_attribute</refname> - <refpurpose>Liefert das erste Merkmal</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ldap_first_attribute</function> - </funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>ber-Kennung</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall das erste Merkmal des Eintrags, im - Fehlerfall falsch. - </para> - <para> - Ähnlich wie Einträge lesen, Merkmale eines bestimmten Eintrags - werden eins nach dem anderen gelesen. - Die <function>ldap_first_attribute</function> Funktion liefert - das erste Merkmal eines Eintrags der durch Ergebnis-Eintrag- - Kennung angegeben wurde. Durch erfolgreichen Aufruf von - <function>ldap_next_attribute</function> erhalten Sie die - restlichen Merkmale. - Der Parameter <parameter>ber-Kennung</parameter> ist die Kennung - eines internen Speicherort-Zeiger. Die Übergabe erfolgt per - Referenz. Die gleiche <parameter>ber-Kennung</parameter> wird an - die Funktion <function>ldap_next_attribute</function> - weitergegeben, die diesen Zeiger dann verändert. - </para> - <para> - Siehe auch <function>ldap_get_attributes</function></para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-first-entry"> - <refnamediv> - <refname>ldap_first_entry</refname> - <refpurpose> - Liefert die Kennung des ersten Ergebnisses - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_first_entry</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall die Ergebnis-Eintrag-Kennung - für den ersten Eintrag, falsch im Fehlerfall. - </para> - <para> - Einträge eines LDAP Ergebnisses werden unter Verwendung der - Funktionen <function>ldap_first_entry</function> und - <function>ldap_next_entry</function> sequentiell gelesen. - Die <function>ldap_first_entry</function> Funktion gibt die - Eintrag-Kennung für den ersten Eintrag im Ergebnis zurück. - Diese Eintrag-Kennung wird dann an die Funktion <function> - lap_next_entry</function> weitergegeben, um sukzessiv die - Einträge des Ergebnisses zu erhalten. - </para> - <para> - Siehe auch <function>ldap_get_entries</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-free-result"> - <refnamediv> - <refname>ldap_free_result</refname> - <refpurpose> - Gibt den belegten Speicher wieder frei - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_free_result</function></funcdef> - <paramdef>int <parameter>Ergebnis-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Um die Ergebnisse zu speichern, wird intern Speicher belegt. - Diesen Speicher können Sie mit der Funktion <function> - ldap_free_result</function> unter Angabe der entsprechenden - <parameter>Ergebnis-Kennung</parameter> wieder freigeben. - Typischerweise wird nach Beendigung des Skripts der gesamte - Ergebnis-Speicher automatisch freigegeben. - </para> - <para> - Falls Ihr Skript sukzessive Suchoperationen durchführt, die - große Ergebnismengen liefern, können Sie <function> - ldap_free_result</function> benutzen, um den Speicherverbrauch - zur Laufzeit niedrig zu halten. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-get-attributes"> - <refnamediv> - <refname>ldap_get_attributes</refname> - <refpurpose> - Liefert Merkmale eines Suchergebnis-Eintrags - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>ldap_get_attributes</function> - </funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int - <parameter>Ergebnis-Eintrag-Kennung</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall wird die gesamte Information eines - Eintrags in einem multidimensionalen Array zurückgegeben; im - Fehlerfall falsch. - </para> - <para> - Die <function>ldap_get_attributes</function> Funktion - wird verwendet um das Lesen der Merkmale und Werte eines Eintrags - im Suchergebnis zu vereinfachen. Der Rückgabewert ist ein - multidimensionales Array aus Merkmalen und Werten. - </para> - <para> - Nachdem Sie einen bestimmten Eintrag in dem Verzeichnis - lokalisiert haben, können Sie mit dieser Funktion herausfinden, - welche Informationen für diesen Eintrag verfügbar sind. Diese - Funktion würden Sie in einer Anwendung verwenden, die - Verzeichniseinträge "durchstöbert" und/oder wo Sie die Struktur - der Verzeichniseinträge nicht kennen. In vielen Anwendungen - suchen Sie nach einem bestimmten Merkmal wie einer email- - Adresse oder einem Nachnamen und interessieren sich nicht dafür, - welche anderen Daten verfügbar sind. - </para> - <para> - <informalexample><literallayout> -return_value["count"] = Anzahl der Merkmale des Eintrags -return_value[0] = das erste Merkmal -return_value[n] = das n-te Merkmal - -return_value["merkmal"]["count"] = Anzahl der Werte des Merkmals -return_value["merkmal"][0] = der erste Wert des Merkmals -return_value["merkmal"][i] = der i-te Wert des Merkmals -</literallayout></informalexample> - - <example> - <title> - Anzeigen der Liste der Merkmale für einen ausgewählten - Verzeichnis-Eintrag - </title> -<programlisting role="php"> -// $ds die Verbindungs-Kennung für das Verzeichnis - -// $sr ein gültiges Suchergebnis eines früheren Aufrufs einer der ldap -// Verzeichnis Suchfunktionen - - -$entry = ldap_first_entry($ds, $sr); - -$attrs = ldap_get_attributes($ds, $entry); - -echo $attrs["count"]." Merkmale für diesen Eintrag:&lt;p>"; - -for ($i=0; $i&lt;$attrs["count"]; $i++) - echo $attrs[$i]."&lt;br>"; -</programlisting> -</example></para> - - <para> - Siehe auch <function>ldap_first_attribute</function> und - <function>ldap_next_attribute</function></para> - - </refsect1> - </refentry> - - - <refentry id="function.ldap-get-dn"> - <refnamediv> - <refname>ldap_get_dn</refname> - <refpurpose>Liefert den DN eines Ergebnis-Eintrags </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ldap_get_dn</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall der DN des Ergebnis-Eintrags, im - Fehlerfall falsch. - </para> - <para> - Die <function>ldap_get_dn</function> Funktion wird verwendet, um - den DN eines Eintrags im Ergebnis herauszufinden. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-get-entries"> - <refnamediv> - <refname>ldap_get_entries</refname> - <refpurpose>Liefert alle Ergebnis-Einträge</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>ldap_get_entries</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall wird die gesamte Information des - Ergebnisses in einem multidimensionalen Array zurückgegeben; im - Fehlerfall falsch. - </para> - <para> - Die <function>ldap_get_entries</function> Funktion wird verwendet - um das Lesen mehrfacher Einträge des Ergebnisses zu vereinfachen - und danach werden die Merkmale und mehfachen Werte gelesen. - Durch einen Funktionsaufruf wird die gesamte Information in einem - multidimensionalen Array zurückgegeben. Die Struktur dieses Array - sieht wie folgt aus. - </para> - <para> - Der Merkmal-Index wird in Kleinbuchstaben umgewandelt. - (Verzeichnis-Server unterscheiden nicht zwischen - Groß-/Kleinschreibung hinsichtlich der Merkmake, aber der - Unterschied ist wichtig, wenn diese Merkmale als Array-Indizes - benutzt werden.) - - <informalexample> -<literallayout> -return_value["count"] = Anzahl der Merkmale im Ergebnis -return_value[0] : bezieht sich auf Einzelheiten des ersten - Eintrags - -return_value[i]["dn"] = DN des i-ten Eintrags im Ergebnis - -return_value[i]["count"] = Anzahl der Merkmale im i-ten Eintrag -return_value[i][j] = das j-te Merkmal des i-ten Eintrags im Ergebnis - -return_value[i]["merkmal"]["count"] = Anzahl der Werte für das - Merkmal im i-ten Eintrag -return_value[i]["merkmal"][j] = der j-te Wert des Merkmals im i-ten - Eintrag -</literallayout> - </informalexample> - </para> - - <para> - Siehe auch <function>ldap_first_entry</function> und - <function>ldap_next_entry</function></para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-get-option"> - <refnamediv> - <refname>ldap_get_option</refname> - <refpurpose> - Liefert den aktuellen Wert für eine gegebene Option - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>ldap_get_option</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>option</parameter></paramdef> - <paramdef>mixed <parameter>retval</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Setzt <parameter>retval</parameter> auf den Wert der gewählten - Option. - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Der Parameter <parameter>option</parameter> kann einer der - folgenden sein: - LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, - LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, - LDAP_OPT_REFERRALS, - LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING, - LDAP_OPT_MATCHED_DN. Beschrieben sind diese unter - <ulink url="&url.ldap.openldap-c-api;">draft-ietf-ldapext-ldap-c- - api-xx.txt</ulink> - </para> - <para> - Diese Funktion steht nur zur Verfügung, wenn Sie OpenLDAP 2.x.x - ODER Netscape Directory SDK x.x benutzen. - Wurde in PHP 4.0.4 hinzugefügt. - </para> - - <para> - <example> - <title>Prüfen der Protokollversion</title> -<programlisting role="php"> -// $ds eine gültige Verbindungs-Kennung für einen Verzeichnis-Server -if (ldap_get_option($ds, LDAP_OPT_PROTOCOL_VERSION, $version)) - echo "Sie benutzen die Protokollversion $version"; -else - echo "Protokollversion konnte nicht bestimmt werden"; -</programlisting> - </example> - </para> - - <para> - Siehe auch <function>ldap_set_option</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-get-values"> - <refnamediv> - <refname>ldap_get_values</refname> - <refpurpose> - Liefert alle Werte eines Ergebnis-Eintrags - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>ldap_get_values</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>merkmal</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall ein Array der Werte des Merkmals, - falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_get_values</function> Funktion wird benutzt um - alle Werte des Merkmals eines Eintrags im Ergebnis zu lesen. Der - Eintrag wird durch - <parameter>Ergebnis-Eintrag-Kennung</parameter> bestimmt. Die - Anzahl der Werte kann über die - Indexierung von "count" des resultierenden Arrays bestimmt - werden. Der Zugriff auf einzelne Werte erfolgt durch einen - ganzzahligen Index im Array. Der erste Indexwert ist 0. - </para> - <para> - Da diese Funktion eine - <parameter>Ergebnis-Eintrag-Kennung</parameter> benötigt, muss - ein Aufruf einer der LDAP Suchfunktionen und einer der - Funktionen, die einen einzelnen Eintrag liefern, vorausgehen. - </para> - <para> - Ihre Anwendung wird entweder hart codiert sein, um bestimmte - Merkmale (wie z.B.: "Nachname" oder "Mail") zu suchen, oder Sie - müssen die Funktion <function>ldap_get_attributes</function> - benutzen, um herauszufinden, welche Merkmale für einen gegebenen - Eintrag vorhanden sind. - </para> - <para> - LDAP erlaubt mehr als einen Eintrag für ein Merkmal, so daß es - z.B. sein kann, dass der Verzeichnis-Eintrag einer Person mehrere - Email-Adressen enthält, die alle mit dem Merkmal "mail" - bezeichnet sind. - - <informalexample> -<literallayout> -return_value["count"] = Anzahl der Werte eines Merkmals -return_value[0] = der erste Wert des Merkmals -return_value[i] = der i-te Wert des Merkmals -</literallayout> - </informalexample> - - <example> - <title> - Liste aller Werte des Merkmals "mail" für einen Verzeichnis- - Eintrag - </title> -<programlisting role="php"> -// $ds eine gültige Verbindungs-Kennung für einen Verzeichnis-Server - -// $sr ein gültiges Suchergebnis eines früheren Aufrufs einer der ldap -// Verzeichnis Suchfunktionen - -// $entry eine gültige Eintrag-Kennung eines früheren Aufrufs einer -// der Funktionen, die einen Verzeichnis-Eintrag zurückgeben - -$values = ldap_get_values($ds, $entry,"mail"); - -echo $values["count"]." Email-Adressen für diesen Eintrag.&lt;p>"; - -for ($i=0; $i &lt; $values["count"]; $i++) - echo $values[$i]."&lt;br>"; -</programlisting> - </example></para> - - </refsect1> - </refentry> - - - <refentry id="function.ldap-get-values-len"> - <refnamediv> - <refname>ldap_get_values_len</refname> - <refpurpose> - Liefert alle binären Werte eines Ergebnis-Eintrags - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>ldap_get_values_len</function> - </funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>merkmal</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall ein Array der Werte des Merkmals, - falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_get_values_len</function> Funktion wird - benutzt um alle Werte des Merkmals eines Eintrags im Ergebnis zu - lesen. Der Eintrag wird durch - <parameter>Ergebnis-Eintrag-Kennung</parameter> bestimmt. Die - Anzahl der Werte kann über die Indexierung von "count" des - resultierenden Arrays bestimmt werden. Der Zugriff auf einzelne - Werte erfolgt durch einen ganzzahligen Index im Array. Der erste - Indexwert ist 0. - </para> - <para> - Diese Funktion wird in der genau gleichen Weise benutzt wie die - Funktion <function>ldap_get_values</function> mit der Aussnahme, - dass hier binäre Daten statt Textdaten behandelt werden. - </para> - <note> - <para> - Diese Funktion wurde in 4.0 hinzugefügt. - </para> - </note> - </refsect1> - </refentry> - - - <refentry id="function.ldap-list"> - <refnamediv> - <refname>ldap_list</refname> - <refpurpose>Einstufige Suche</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_list</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>basis_dn</parameter></paramdef> - <paramdef>string <parameter>filter</parameter></paramdef> - <paramdef>array - <parameter><optional>merkmale</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>attrsonly</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>größenbegrenzung</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>zeitbegrenzung</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>deref</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall eine Such-Ergebnis-Kennung,im - Fehlerfall falsch. - </para> - <para> - Die <function>ldap_list</function> Funktion führt die Suche für - einen gegebenen Filter im Verzeichnis mit der Reichweite von - LDAP_SCOPE_ONELEVEL durch. - </para> - <para> - LDAP_SCOPE_ONELEVEL bedeutet, dass die Suche nur Informationen - liefert, die direkt unterhalb der Stufe liegen, die durch die - Angabe des Basis dn im Auruf bestimmt wird. (Das entspricht der - Eingabe von "ls", die eine Liste von Dateien und Verzeichnissen - des aktuellen Arbeitsverzeichnisses anzeigt.) - </para> - <para> - Der Aufruf dieser Funktion nimmt 5 optionale Parameter entgegen. - Siehe die Anmerkungen zu <function>ldap_search</function>. - <note> - <para> - Diese wahlfreien Parameter wurden in 4.0.2 hinzugefügt: - <parameter>attrsonly</parameter>, - <parameter>größenbegrenzung</parameter>, - <parameter>zeitbegrenzung</parameter>, - <parameter>deref</parameter>. - </para> - </note> - - <example> - <title> - Erzeugung einer Liste aller Organisationseinheiten einer - Organisation - </title> -<programlisting role="php3"> -// $ds gültige Verbindungs-Kennung für einen Verzeichnis-Server - -$basis_dn = "o=Meine Firma, c=DE"; -$nur_dieses = array("ou"); - -$sr=ldap_list($ds, $basis_dn, "ou=*", $nur_dieses); - -$info = ldap_get_entries($ds, $sr); - -for ($i=0; $i&lt;$info["count"]; $i++) - echo $info[$i]["ou"][0] ; -</programlisting> -</example></para> - <para> - Seit der Version 4.0.5 ist es außerdem möglich parallele Suchen - durchzuführen. Für Details siehe - <function>ldap_search</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-modify"> - <refnamediv> - <refname>ldap_modify</refname> - <refpurpose>Verändern eines LDAP-Eintrags</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_modify</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>array <parameter>eintrag</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_modify</function> Funktion wird verwendet, um - bestehende Einträge in einem LDAP-Verzeichnis zu ändern. - Die Struktur des Eintrags ist die gleiche wie bei <function> - ldap_add</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-mod-add"> - <refnamediv> - <refname>ldap_mod_add</refname> - <refpurpose> - Hinzufügen von Merkmalswerten zu aktuellen Merkmalen - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_mod_add</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>array <parameter>eintrag</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Diese Funktion fügt Merkmal(e) zum angegebenen dn hinzu. - Die Änderung wird auf der Merkmalsebene durchgeführt im - Gegensatz zur Objektebene. Das Hinzufügen auf der Objektebene - wird durch die Funktion <function>ldap_add</function> geleistet. - </para> - </refsect1> - </refentry> - - <refentry id="function.ldap-mod-del"> - <refnamediv> - <refname>ldap_mod_del</refname> - <refpurpose> - Löschen von Merkmalswerten aktueller Merkmale - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_mod_del</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>array <parameter>eintrag</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Diese Funktion entfernt ein oder mehrere Merkmale vom angegebenen - dn. Die Änderung wird auf der Merkmalsebene durchgeführt im - Gegensatz zur Objektebene. Das Löschen auf Objektebene wird - durch die Funktion <function>ldap_delete</function> geleistet. - </para> - </refsect1> - </refentry> - - <refentry id="function.ldap-mod-replace"> - <refnamediv> - <refname>ldap_mod_replace</refname> - <refpurpose> - Ersetzen von Merkmalswerten mit neuen Merkmalswerten - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_mod_replace</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>array <parameter>eintrag</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Diese Funktion ersetzt ein oder mehrere Merkmale vom angegebenen - dn. Die Änderung wird auf der Merkmalsebene durchgeführt im - Gegensatz zur Objektebene. Änderungen auf der Objektebene wird - durch die Funktion <function>ldap_modify</function> geleistet. - </para> - </refsect1> - </refentry> - - <refentry id="function.ldap-next-attribute"> - <refnamediv> - <refname>ldap_next_attribute</refname> - <refpurpose> - Liefert das nächste Merkmal im Ergebnis - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ldap_next_attribute</function> - </funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>ber_Kennung</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: im Erfolgsfall das nächste Merkmal eines Eintrags, - im Fehlerfall falsch. - </para> - <para> - Die <function>ldap_next_attribute</function> Funktion wird - aufgerufen, um die Merkmale eines Eintrags zu erhalten. Der - interne Status des Zeigers wird durch die <parameter> - ber_Kennung</parameter> bestimmt. Diese wird mittels Referenz an - die Funktion weitergegeben. - Der erste Aufruf von <function>ldap_next_attribute</function> - erfolgt mit der <parameter>Ergebnis-Eintrag-Kennung</parameter>, - die von <function>ldap_first_attribute</function> zurückgegeben - wurde. - </para> - <para> - Siehe auch <function>ldap_get_attributes</function> - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-next-entry"> - <refnamediv> - <refname>ldap_next_entry</refname> - <refpurpose> - Liefert den nächsten Eintrag des Ergebnisses - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_next_entry</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: Im Erfolgsfall wird die Eintrags-Kennung für den - nächsten Eintrag des Ergebnisses zurückgegeben. Das Lesen der - Einträge wird mit <function>ldap_first_entry</function> - gestartet. - Wenn keine weiteren Einträge im Ergebnis vorhanden sind wird - falsch zurückgegeben. - </para> - <para> - Die <function>ldap_next_entry</function> Funktion wird verwendet, - um die Einträge zu erhalten, die im Ergebnis gespeichert sind. - Wiederholtes aufrufen von <function>ldap_next_entry</function> - liefert einen Eintrag nach dem anderen, solange bis kein Eintrag - mehr vorliegt. Der erste Aufruf von <function> - ldap_next_entry</function> erfolgt nach dem Aufruf von - <function>ldap_first_entry</function> mit der Ergebnis-Kennung, - die von <function>ldap_first_entry</function> zurückgegeben - wurde. - </para> - <para> - Siehe auch <function>ldap_get_entries</function> - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-read"> - <refnamediv> - <refname>ldap_read</refname> - <refpurpose>Lesen eines Eintrags</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_read</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>basis_dn</parameter></paramdef> - <paramdef>string <parameter>filter</parameter></paramdef> - <paramdef>array - <parameter><optional>merkmale</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>attrsonly</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>größenbegrenzung</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>zeitbegrenzung</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>deref</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: Im Erfolgsfall eine Such-Ergebnis-Kennung, falsch - im Fehlerfall. - </para> - <para> - Die <function>ldap_read</function> Funktion führt die Suche für - einen gegebenen Filter im Verzeichnis mit der Reichweite von - LDAP_SCOPE_BASE durch. Das ist äquivalent zum Lesen eines - Eintrags in einem Verzeichnis. - </para> - <para> - Ein leerer Filter ist nicht erlaubt. Wenn Sie wirklich alle - Informationen für einen Eintrag erhalten möchten, müssen Sie - einen Filter der Art "objectClass=*" verwenden. Kennen Sie die - Typen der Einträge die auf dem Verzeichnis-Server benutzt werden, - können Sie einen passenden Filter wie z.B."objectClass= - inetOrgPerson" verwenden. - </para> - <para> - Der Aufruf dieser Funktion nimmt 5 optionale Argumente - entgegen. Siehe Anmerkungen zu <function>ldap_search</function>. - </para> - <note> - <para> - Diese wahlfreien Argumente wurden in 4.0.2 hinzugefügt: - <parameter>attrsonly</parameter>, - <parameter>größenbegrenzung</parameter>, - <parameter>zeitbegrenzung</parameter>, - <parameter>deref</parameter>. - </para> - </note> - <para> - Seit der Version 4.0.5 ist es außerdem möglich parallele Suchen - durchzuführen. Für Details siehe - <function>ldap_search</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-rename"> - <refnamediv> - <refname>ldap_rename</refname> - <refpurpose> - Verändert den Namen eines Eintrags - </refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>ldap_rename</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>dn</parameter></paramdef> - <paramdef>string <parameter>neuerrdn</parameter></paramdef> - <paramdef>string <parameter>neueeltern</parameter></paramdef> - <paramdef>bool <parameter>löschealtenrdn</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Der Eintrag, der durch <parameter>dn</parameter> gegeben ist, - wird umbenannt/enfernt. Der neue RDN wird durch <parameter> - neuerrdn</parameter> bestimmt, der neue Eltern-/übergeordnete - Eintrag wird durch <parameter>neueeltern</parameter> bestimmt. - Wenn das Argument <parameter>löschealtenrdn</parameter> wahr ist, - wird der alte Wert/die alten Werte von RDN enfernt, andernfalls - wird der alte Wert/die alten Werte als nicht-eindeutige (non- - distinguished) Werte des Eintrags beibehalten. - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Diese Funktion steht nur zur Verfügung, wenn Sie OpenLDAP 2.x.x - ODER Netscape Directory SDK x.x benutzen. Wurde in PHP 4.0.5 - hinzugefügt. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-search"> - <refnamediv> - <refname>ldap_search</refname> - <refpurpose>Suche im LDAP Baum</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_search</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>string <parameter>base_dn</parameter></paramdef> - <paramdef>string <parameter>filter</parameter></paramdef> - <paramdef>array - <parameter><optional>merkmale</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>attrsonly</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>größenbegrenzung</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>zeitbegrenzung</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>deref</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: eine Such-Ergebnis-Kennung im Erfolgsfall, falsch - im Fehlerfall. - </para> - <para> - Die <function>ldap_search</function> Funktion führt die Suche für - einen gegebenen Filter im Verzeichnis mit der Reichweite von - LDAP_SCOPE_SUBTREE durch. Das ist äquivalent zu einer Suche im - ganzen Verzeichnis.<parameter>base_dn</parameter> legt den Basis - DN für das Verzeichnis fest. - </para> - <para> - Der optionale vierte Parameter kann benutzt werden, um die - Rückgabewerte des Servers so einzuschränken, dass nur die - tatsächlich benötigten Merkmale und ihre zugehörigen Werte in der - Ergebnismenge enthalten sind. Dieses Vorgehen ist um einiges - effizienter als die standardmäßige Vorgehensweise (diese liefert - alle Merkmale und alle zugehörigen Werte). Aus diesem Grund ist - die Angabe des vierten Parameters als gute Praxis zu empfehlen. - </para> - <para> - Der vierte Parameter ist ein Standard PHP Zeichenketten Array der - benötigten Merkmale, z.B. array("mail","sn","cn"). Beachten Sie, - dass der DN immer zurückgeliefert wird, ohne Rücksicht darauf, - welche Merkmalstypen angefragt wurden. - </para> - <para> - Beachten Sie weiterhin, dass manche Verzeichnis-Server so - konfiguriert sind, dass sie nicht mehr als eine vorbestimmte - Anzahl an Einträgen zurückliefern. Sollte dies der Fall sein, - zeigt Ihnen der Server an, dass nur eine Teilmenge des - Ergebnisses zurückgeliefert wurde. Diesen Hinweis erhalten Sie - auch, wenn Sie den sechsten Parameter - <parameter>größenbegrenzung</parameter> mit angegeben hatten, um - die Anzahl der angefragten Einträge einzuschränken. - </para> - <para> - Der fünfte Parameter <parameter>attrsonly</parameter> sollte auf - 1 gesetzt werden, wenn Sie nur Merkmalstypen erhalten möchten. - Wenn der Wert auf 0 steht, erhalten Sie sowohl Merkmalstypen als - auch Merkmalswerte. Das ist das Standard Verhalten. - </para> - <para> - Mit dem sechsten Parameter - <parameter>größenbegrenzung</parameter> ist es möglich, die - Anzahl der Einträge, die Sie erhalten, zu begrenzen. - Wenn Sie diesen Wert auf 0 setzen, bedeutet dies keine - Beschränkung der Ergegnismenge. - ANMERKUNG: Dieser Parameter kann eine serverseitig gesetzte - Beschränkung NICHT überschreiben. Sie haben nur die Möglichkeit - die Beschränkung noch weiter herabzusetzen. - </para> - <para> - Der siebte Parameter <parameter>zeitbegrenzung</parameter> legt - die Zahl in Sekunden fest, die auf die Suche verwendet wird. - Wenn Sie diesen Wert auf 0 setzen, bedeutet dies keine - Beschränkung der Zeit. - ANMERKUNG: Dieser Parameter kann eine serverseitig gesetzte - Zeitbegrenzung NICHT überschreiben. Sie haben nur die - Möglichkeit die Beschränkung noch weiter herabzusetzen. - </para> - <para> - Der achte Parameter <parameter>deref</parameter> gibt an, wie - Aliase während einer Suche behandelt werden. - Wert kann einer der folgenden sein: - <itemizedlist> - <listitem> - <simpara> - LDAP_DEREF_NEVER - (Standard) Aliase werden nie aufgelöst. - </simpara> - </listitem> - <listitem> - <simpara> - LDAP_DEREF_SEARCHING - Aliase sollen während der Suche - aufgelöst werden, aber nicht dann, wenn das Basisobjekt der - Suche ermittelt wird. - </simpara> - </listitem> - <listitem> - <simpara> - LDAP_DEREF_FINDING - Aliase sollen aufgelöst werden, wenn das - Basisobjekt ermiitelt wird, aber nicht während der Suche. - </simpara> - </listitem> - <listitem> - <simpara> - LDAP_DEREF_ALWAYS - Aliase sollen immer aufgelöst werden. - </simpara> - </listitem> - </itemizedlist> - </para> - <para> - Diese optionalen Parameter wurden in 4.0.2 hinzugefügt: - <parameter>attrsonly</parameter>, - <parameter>größenbegrenzung</parameter>, - <parameter>zeitbegrenzung</parameter>, - <parameter>deref</parameter>. - </para> - <para> - Der Suchfilter kann einfach oder komplizierter sein, wenn sie - boolsche Operatoren in dem Format verwenden, wie in der LDAP - Dokumentation beschrieben (siehe <ulink url="&url.ldap.filters;"> - Netscape Directory SDK</ulink> für die vollständige Information - über Filter). - </para> - <para> - Das untenstehende Beispiel liefert die Organisationseinheit, den - Familiennamen, den Vornamen und die Email-Addresse aller Personen - in "Meine Firma" deren Familien- oder Vorname die Zeichenkette - $person enhält. In diesem Beispiel wird ein boolscher Filter - verwendet, um den Server zu veranlassen, nach Informationen in - mehr als einem Merkmal zu suchen. - - <example> - <title>LDAP Suche</title> -<programlisting role="php"> -// $ds gültige Verbindungs-Kennung für einen Verzeichnis-Server - -// $person ein Teil oder der vollständige Name einer Person, z.B. - "Jo" - -$dn = "o=Meine Firma, c=DE"; -$filter="(|(sn=$person*)(vorname=$person*))"; -$justthese = array( "ou", "sn", "vorname", "mail"); - -$sr=ldap_search($ds, $dn, $filter, $justthese); - -$info = ldap_get_entries($ds, $sr); - -print $info["count"]." gefundene Einträge&lt;p>"; -</programlisting> - </example> - </para> - <para> - Seit der Version 4.0.5 ist es außerdem möglich parallele Suchen - durchzuführen. Um dies zu verwirklichen benutzen Sie als erstes - Argument einen Array von Verbindungs-Kennungen, statt einer - einzelnen Verbindungs-Kennung. Falls Sie nicht den gleichen Basis - DN und den gleichen Filter für alle Suchen verwenden möchten, - können Sie ebenso einen Array von Basis DNs und/oder einen Array - von Filtern benutzen. Diese Arrays müssen die gleiche Größe wie - das Array der Verbindungs-Kennungen haben, da die ersten Einträge - der Arrays für eine Suche verwendet werden, die zweiten Einträge - für eine andere Suche und so weiter. Wenn Sie parallel suchen - erhalten Sie ein Array von Such-Ergebnis-Kennungen, außer im Fall - eines Fehlers, dann liefert der Eintrag zur entsprechenden Suche - falsch zurück. Das entspricht ganz genau dem Wert der - normalerweise zurückgeliefert wird, außer dass Sie immer eine - Ergebnis-Kennung erhalten, wenn Sie eine Suche durchgeführt - haben. Es treten einige seltene Fälle auf, wo eine normale Suche - falsch zurückgibt, während die parallele Suche eine Kennung - zurückliefert. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-set-option"> - <refnamediv> - <refname>ldap_set_option</refname> - <refpurpose>Setzt den Wert der gegebenen Option</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>ldap_set_option</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - <paramdef>int <parameter>option</parameter></paramdef> - <paramdef>mixed <parameter>neuerwert</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Setzt den Wert der bestimmten Option auf - <parameter>neuerwert</parameter>. - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Der Parameter <parameter>option</parameter> kann einer der - folgenden sein: - LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, - LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, - LDAP_OPT_REFERRALS, - LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING, - LDAP_OPT_MATCHED_DN, LDAP_OPT_SERVER_CONTROLS, - LDAP_OPT_CLIENT_CONTROLS. - Hier eine kurze Beschreibung, schauen Sie unter - <ulink url="&url.ldap.openldap-c-api;">draft-ietf-ldapext-ldap-c- - api-xx.txt</ulink> nach Details. - </para> - <para> - Die Optionen LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, - LDAP_OPT_TIMELIMIT, LDAP_OPT_PROTOCOL_VERSION und - LDAP_OPT_ERROR_NUMBER haben einen ganzzahligen Wert, - LDAP_OPT_REFERRALS und LDAP_OPT_RESTART haben einen boolschen - Wert und die Optionen LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING - und LDAP_OPT_MATCHED_DN bestehen aus einer Zeichenkette. - Das erste Beispiel veranschaulicht deren Gebrauch. Die Optionen - LDAP_OPT_SERVER_CONTROLS and LDAP_OPT_CLIENT_CONTROLS benötigen - eine Kontrolliste, d.h. der Wert muss ein Array aus Kontrollen - sein. Eine Kontrolle besteht aus einer <emphasis>oid</emphasis> - die die Kontrolle identifiziert, einem wahlweisen <emphasis> - wert</emphasis>, und einem wahlweisen Kennzeichen für <emphasis> - criticality</emphasis>. Bei PHP wird eine Kontrolle durch ein - Array angegeben. Dieses Array enthält ein Element mit dem - Schlüssel <emphasis>oid</emphasis> und einer Zeichenkette als - Wert und zwei optionalen Elementen. Die optionalen Elemente sind - Schlüssel <emphasis>wert</emphasis> mit einer Zeichenkette als - Wert und dem Schlüssel <emphasis>iscritical</emphasis> mit einem - boolschen Wert. Der vorgegebene Wert von <emphasis> - iscritical</emphasis> ist <emphasis>&false;</emphasis> falls Sie - nichts angeben. - Schauen Sie sich das zweite Beispiel weiter unten an. - </para> - <para> - Diese Funktion steht nur zur Verfügung, wenn Sie OpenLDAP 2.x.x - ODER Netscape Directory SDK x.x verwenden und wurde in PHP 4.0.4 - hinzugefügt. - </para> - <para> - <example> - <title>Setzen der Protokollversion</title> -<programlisting role="php"> -// $ds ist eine gültige Verbindungs-Kennung für einen Verzeichnis- -// Server -if (ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)) - echo "Verwenden von LDAPv3"; -else - echo "Kann das Protokoll nicht auf Version 3 setzen"; -</programlisting> - </example> - <example> - <title>Setzen der Server Kontrollen</title> -<programlisting role="php"> -// $ds ist eine gültige Verbingund-Kennung für einen Verzeichnis- -// Server -// Kontrolle ohne Wert -$ctrl1 = array("oid" => "1.2.752.58.10.1", "iscritical" => TRUE); -// iscritical hat den vorgegebenen Wert FALSE -$ctrl2 = array("oid" => "1.2.752.58.1.10", "value" => "magic"); -// Versuch, beide Kontrollen zu setzen -if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, -$ctrl2))) - echo "Kann die Server Kontrollen nicht setzen"; -</programlisting> - </example> - </para> - <para> - Siehe auch <function>ldap_get_option</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.ldap-unbind"> - <refnamediv> - <refname>ldap_unbind</refname> - <refpurpose>Unbind von einem LDAP Verzeichnis</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ldap_unbind</function></funcdef> - <paramdef>int <parameter>Verbindungs-Kennung</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. - </para> - <para> - Die <function>ldap_unbind</function> Funktion führt ein unbind - auf ein LDAP Verzeichnis aus. - </para> - </refsect1> - </refentry> - </reference> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +<reference id="ref.ldap"> +<title>LDAP Funktionen</title> +<titleabbrev>LDAP</titleabbrev> + +<partintro> +<sect1 id="ldap.intro"> +<title>Einführung zu LDAP</title> + <para> + LDAP steht für Lightweight Directory Access Protocol und ist + ein Protokoll um auf "Directory Servers" - "Verzeichnis- + Server" - zuzugreifen. + Das Verzeichnis ist dabei eine spezielle Art einer Datenbank, + das Informationen in einer Baumstruktur bereithält. + </para> + <para> + Das Konzept ist dabei ähnlich der Verzeichnisstruktur Ihrer + Festplatte, mit der Ausnahme, daß in diesem Zusammenhang + das Wurzelverzeichnis "Die Welt" ist und die + Unterverzeichnisse der ersten Ebene "Länder" abbilden. + Die weiteren Verzeichnisse unterhalb der Länderebene enthalten + Einträge für Firmen, Organisationen oder Städte. Noch tiefer + geschachtelt stehen Verzeichniseinträge für Menschen und + vielleicht für Ausstattung oder Dokumente. + </para> + <para> + Um auf eine Datei in einem Unterverzeichnis auf Ihrer + Festplatte zu verweisen, könnten Sie eine Schreibweise wie + folgt verwenden + </para> + <literallayout> + /usr/local/meine_daten/doku + </literallayout> + <para> + Die Schrägstriche markieren jeden Teil in diesem Verweis und + die Sequenz wird von links nach rechts gelesen. + </para> + <para> + Das entsprechende Gegenstück zu einer voll qualifizierten + Dateireferenz ist in LDAP der "Eindeutige Name" + ("distinguished name"), der Einfachheit halber als "dn" + bezeichnet. + Ein Beispiel für einen solchen dn könnte sein + </para> + <literallayout> + cn=Hans Mustermann,ou=Buchhaltung,o=Meine Firma,c=DE + </literallayout> + <para> + Das Komma markiert jeden Teil in diesem Verweis und die + Sequenz wird von rechts nach links gelesen. + Diesen dn würden Sie wie folgt lesen ... + </para> + <literallayout> + Land = DE + Organisation (organisation) = Meine Firma + Organisationseinheit (organisational unit) = Buchhaltung + Einfacher Name (commonName) = Hans Mustermann + </literallayout> + <para> + In der gleichen Weise, in der es keine allgemeinverbindlichen + Regeln gibt, wie Sie die Verzeichnisstruktur Ihrer Festplatte + organsieren, kann der Verwalter eines Verzeichnis-Servers jede + beliebige Struktur implementieren, die für den Einsatzzweck + sinnvoll ist. + Trotzdem gibt es einige Konventionen die benutzt werden. + Die Botschaft ist folgende: Sie können keinen Code schreiben + um auf einen Verzeichnis-Server zuzugreifen, ohne etwas über + dessen Struktur zu wissen. Genauso wenig können Sie eine + Datenbank nutzen ohne Kenntnis darüber, was in derselben + vorhanden ist. + </para> +</sect1> + +<sect1 id="ldap-example"> +<title>Komplettes Code Beispiel</title> + <para> + Informationen von einem Verzeichnis-Server beziehen für alle + Einträge bei denen der Nachname mit "S" beginnt. Darstellung + eines Auszugs mit Name und Email-Adresse. + </para> + + <example> + <title>LDAP Such-Beispiel</title> + <programlisting role="php"> + &lt;?php + // Grundlegende Abfolge bei LDAP ist verbinden, binden, suchen, + // interpretieren des Sucheergebnisses, Verbindung schließen + + echo "&lt;h3>LDAP query Test&lt;/h3>"; + echo "Verbindung ..."; + $ds=ldap_connect("localhost"); // muss ein gültiger LDAP Server + // sein! + + echo "Ergebnis der Verbindung: ".$ds."&lt;p>"; + + if ($ds) { + echo "Bindung ..."; + $r=ldap_bind($ds); // das ist ein "anonymer" bind, + // typischerweise nur Lese Zugriff + echo "Ergebnis der Bindung ".$r."&lt;p>"; + + echo "Suche nach (sn=S*) ..."; + // Suchen des Nachnamen-Eintrags + $sr=ldap_search($ds,"o=Meine Firma, c=DE", "sn=S*"); + echo "Ergebnis der Suche ".$sr."&lt;p>"; + + echo "Anzahl der Einträge, die gefunden wurden + .ldap_count_entries($ds,$sr)."&lt;p>"; + + echo "Einträge holen ...&lt;p>"; + $info = ldap_get_entries($ds, $sr); + echo "Daten für ".$info["count"]." Items gefunden:&lt;p>"; + + for ($i=0; $i&lt;$info["count"]; $i++) { + echo "dn ist: ". $info[$i]["dn"] ."&lt;br>"; + echo "erster cn Eintrag: ". $info[$i]["cn"][0] ."&lt;br>"; + echo "erster email Eintrag: ". $info[$i]["mail"][0] + ."&lt;p>"; + } + + echo "Verbindung schließen"; + ldap_close($ds); + + } else { + echo "&lt;h4>Verbindung zu LDAP Server nicht möglich&lt;/h4>"; + } + ?> + </programlisting> + </example> + +<sect2 id="ldap.using"> +<title>Verwenden der PHP LDAP Aufrufe</title> + <para> + Sie müssen sich die LDAP Client Bibliotheken herunterladen und + übersetzen. Sie können entweder das ldap-3.3 Packet von der + University of Michigan oder das Netscape Directory SDK 3.0 + verwenden. Ebenso müssen Sie Ihr PHP mit LDAP Unterstützung + aktiviert neu übersetzen bevor die PHP LDAP-Aufrufe + funktionieren. + </para> + <para> + Bevor Sie die LDAP Aufrufe benutzen können, müssen Sie folgendes + wissen... + <itemizedlist> + <listitem> + <para> + Den Namen oder die Adresse des Verzeichnis-Servers den Sie + benutzen wollen + </para> + </listitem> + <listitem> + <para> + Den "Basis dn" des Servers (den Teil des Weltverzeichnisses, + das auf diesem Server eingerichtet ist, das könnte "o=Meine + Firma,c=DE" sein. + </para> + </listitem> + <listitem> + <para> + Brauchen Sie ein Passwort um auf den Server zuzugreifen? + (Viele Server bieten Lesezugriff für einen "anonymen bind", + verlangen aber ein Passwort für alles weitere) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Die typische Abfolge von LDAP Aufrufen in einer Anwendung folgen + diesem Muster + <literallayout> + ldap_connect() // Aufbau einer Verbindung zum Server + + connection to server + | + ldap_bind() // anonymes oder authentifiziertes "login" + | + mache irgendwas, z.B. Verzeichnis durchsuchen oder aktualisieren + und stelle das Ergebnis dar + | + ldap_close() // "logout" +</literallayout></para> + +</sect2> +<sect2 id="ldap.moreinfo"> +<title>Mehr Informationen</title> + <para> + Viele Informationen finden Sie unter + </para> + + <itemizedlist> + <listitem> + <para> + <ulink url="&url.ldap.netscape;">Netscape</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="&url.ldap.michigan;">University of Michigan</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="&url.ldap.openldap;">OpenLDAP Project</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="&url.ldap.ldapworld;">LDAP World</ulink> + </para> + </listitem> + </itemizedlist> + + <para> + Das Netscape SDK enthält einen hilfreichen Programmer´s Guide im + .html Format. + </para> +</sect2> +</sect1> + +</partintro> + + +<refentry id="function.ldap-add"> +<refnamediv> + <refname>ldap_add</refname> + <refpurpose> + Einträge einem LDAP Verzeichnis hinzufügen + </refpurpose> +</refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_add</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>array <parameter>eintrag</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_add</function> Funktion wird benutzt um + Einträge einem Verzeichnis hinzuzufügen. Die DN des Eintrags, der + hinzugefügt werden soll wird durch dn bestimmt. Array eintrag + bestimmt die Informationen des Eintrags. Die Werte in den + Einträgen werden durch individuelle Merkmale indiziert. + Im Fall von mehreren Werten für ein Merkmal werden diese durch + die Verwendung von Zahlen indiziert, die bei 0 beginnen. + </para> + <informalexample> +<literallayout> + eintrag["merkmal1"] = wert + eintrag["merkmal2"][0] = wert1 + eintrag["merkmal2"][1] = wert2 +</literallayout> + </informalexample> + <example> + <title>Komplettes Beispiel mit authentifiziertem bind</title> + +<programlisting role="php"> +&lt;?php +$ds=ldap_connect("localhost"); // Annahme: der LDAP Server befindet + // sich auf diesem Host + +if ($ds) { + // bind mit passendem dn für aktulisierenden Zugriff + $r=ldap_bind($ds,"cn=root, o=Meine Firma, c=DE", "geheim"); + + // Daten vorbereiten + $info["cn"]="Hans Mustermann"; + $info["sn"]="Mustermann"; + $info["mail"]="MustermannH@firma.de"; + $info["objectclass"]="person"; + + // hinzufügen der Daten zum Verzeichnis + $r=ldap_add($ds, "cn=Hans Mustermann, o=Meine Firma, c=DE", + $info); + + ldap_close($ds); +} else { + echo "Verbindung zum LDAP Server nicht möglich!"; +} +?> +</programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.ldap-bind"> + <refnamediv> + <refname>ldap_bind</refname> + <refpurpose>Bindung zu einem LDAP Verzeichnis</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_bind</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter><optional>bind_rdn</optional> + </parameter></paramdef> + <paramdef>string <parameter><optional>bind_kennwort</optional> + </parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Bindung für ein LDAP Verzeichnis mit angegebenem RDN und + Kennwort. Rückgabewert: wahr im Erfolgsfall, falsch im + Fehlerfall. + </para> + <para> + Die <function>ldap_bind</function> Funktion führt eine bind + Operation auf einem Verzeichnis aus. bind_rdn und bind_kennwort + sind optional, wenn diese fehlen wird ein anonymes bind versucht. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-close"> + <refnamediv> + <refname>ldap_close</refname> + <refpurpose>Verbindung zum LDAP Server schliessen</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_close</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_close</function> Funktion schließt die + Verbindung zum LDAP Server die zur + <parameter>Verbindungs-Kennung</parameter> gehört. + </para> + <para> + Der Aufruf dieser Funktion ist intern identisch zu + <function>ldap_unbind</function>. Die LDAP API benutzt den Aufruf + <function>ldap_unbind</function>, so dass Sie vielleicht diese + Funktion benutzen sollten, anstatt<function> + ldap_close</function> zu verwenden.</para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-compare"> + <refnamediv> + <refname>ldap_compare</refname> + <refpurpose> + Vergleicht gefundenen Wert eines Merkmal in einem Eintrag, der + durch Angabe von dn destimmt wird. + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_compare</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>string <parameter>merkmal</parameter></paramdef> + <paramdef>string <parameter>wert</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Rückgabewert: wahr, wenn <parameter>wert</parameter> gefunden + wird, ansonsten falsch. Tritt ein Fehler auf, wird -1 + zurückgegeben. + </simpara> + <para> + <function>ldap_compare</function> vergleicht den<parameter> + wert</parameter> eines <parameter>merkmal</parameter> mit dem + Wert des gleichen Merkmals in dem LDAP Verzeichniseintrag der + durch <parameter>dn</parameter> bestimmt wurde. + </para> + <simpara> + Das folgende Beispiel zeigt, wie überprüft wird, ob ein gegebenes + Kennwort mit dem Kennwort übereinstimmt oder nicht, das in dem + durch DN bestimmten Eíntrag gespeichert ist. + </simpara> + <example> + <title>Komplettes Beispiel einer Kennwort-Überprüfung</title> + <programlisting role="php"> +&lt;?php + +$ds=ldap_connect("localhost"); // Annahme: der LDAP Server befindet + // sich auf diesem Host + +if ($ds) { + + // binden + if(ldap_bind($ds)) { + + // Daten vobereiten + $dn = "cn=Helga Olsen, ou=Meine Einheit, o=Meine Firma, c=FI"; + $value = "geheimeskennwort"; + $attr = "kennwort"; + + // vergleiche Werte + $r=ldap_compare($ds, $dn, $attr, $value); + + if ($r === -1) { + echo "Fehler: ".ldap_error($ds); + } elseif ($r === TRUE) { + echo "Kennwort korrekt."; + } elseif ($r === FALSE) { + echo "Falsch geraten! Kennwort nicht korrekt."; + } + + } else { + echo "Keine Bindung zum LDAP Server möglich."; + } + + ldap_close($ds); + +} else { + echo "Keine Verbindung zum LDAP Server möglich."; +} +?&gt; + + </programlisting> + </example> + <note> + <para> + <function>ldap_compare</function> kann NICHT für Vergleiche von + BINÄREN Werten benutzt werden! + </para> + </note> + <note> + <para> + Diese Funktion wurde in 4.0.2 hinzugefügt. + </para> + </note> + </refsect1> + </refentry> + + + <refentry id="function.ldap-connect"> + <refnamediv> + <refname>ldap_connect</refname> + <refpurpose>Verbindung zu einem LDAP Server</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_connect</function></funcdef> + <paramdef>string <parameter><optional>hostname</optional> + </parameter></paramdef> + <paramdef>int <parameter><optional>port</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: Eine positive Verbindungs-Kennung im Erfolgsfall, + falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_connect</function> Funktion öffnet eine + Verbindung zu einem LDAP Server auf einem bestimmten<parameter> + hostname</parameter> und <parameter>port</parameter>. Beide + Argumente sind optional. Wenn keine Argumente angegeben werden, + wird die Verbindungs-Kennung einer eventuell schon geöffneten + Verbindung zurückgeliefert. Wird nur der<parameter> + hostname</parameter> angegeben, wird für den Port der Standarport + 389 benutzt. + </para> + <para> + Bei Verwendung von OpenLDAP 2.x.x können Sie eine URL statt des + Hostnamens angeben. + Um LDAP mit SSL-Unterstützzung zu verwenden, übersetzen Sie + OpenLDAP mit SSL-Unterstützung, PHP mit SSL und verwenden + ldaps://Hostname/ als Host Argument. Das Port Argument wird bei + der Verwendung von URLs nicht benutzt. + URL und SSL Unterstützung wurden in 4.0.4 hinzugefügt</para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-count-entries"> + <refnamediv> + <refname>ldap_count_entries</refname> + <refpurpose>Zählt die Anzahl der Einträge bei einer + Suche</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_count_entries</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: Anzahl der Einträge im Ergebnis, falsch im + Fehlerfall.</para> + <para> + Die <function>ldap_count_entries</function> Funktion liefert die + Anzahl der Einträge im gespeicherten Ergebnis einer vorher + durchgeführten Suchoperation. + <parameter>Ergebnis-Kennung</parameter> bezeichnet das interne + LDAP Ergebnis. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-delete"> + <refnamediv> + <refname>ldap_delete</refname> + <refpurpose>Löscht einen Eintrag aus einem Verzeichnis + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_delete</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_delete</function> Funktion löscht einen + einzelnen Eintrag aus einem LDAP Verzeichnis, das im dn angegeben + wurde. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-dn2ufn"> + <refnamediv> + <refname>ldap_dn2ufn</refname> + <refpurpose> + Konvertiert DN in ein benutzerfreundliches Namensformat + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ldap_dn2ufn</function></funcdef> + <paramdef>string <parameter>dn</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Die <function>ldap_dn2ufn</function> Funktion wird verwendet um + einen DN in einer benutzerfreundlicheren Form darzustellen, wobei + die Typen-Namen wegfallen. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-err2str"> + <refnamediv> + <refname>ldap_err2str</refname> + <refpurpose> + Konvertiert eine LDAP Fehlernummer in einen Fehlertext + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ldap_err2str</function></funcdef> + <paramdef>int <parameter>Fehlernummer</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: Fehlertext.</para> + <para> + Diese Funktion liefert den Fehlertext der die Fehlernummer + erklärt. + Während LDAP Fehlernummern standardisiert sind, liefern + unterschiedliche Bibliotheken unterschiedliche oder sogar + lokalspezifische Fehlermeldungen. Deshalb sollten Sie nie auf + eine spezielle Fehlermeldung prüfen, sondern immer eine + Fehlernummer verwenden. + </para> + <para> + Siehe auch <function>ldap_errno</function> und + <function>ldap_error</function>. + + <example> + <title>Aufzählung aller LDAP Fehlermeldungen</title> +<programlisting role="php"> +&lt;?php + for($i=0; $i&lt;100; $i++) { + printf("Fehler $i: %s&lt;br>\n", ldap_err2str($i)); + } +?> +</programlisting> + </example> + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-errno"> + <refnamediv> + <refname>ldap_errno</refname> + <refpurpose> + Liefert die LDAP Fehlernummer des letzten LDAP Kommandos + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_errno</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: LDAP Fehlernummer des letzten LDAP Kommandos für + diese Verbindung. + </para> + <para> + Diese Funktion liefert die standardisierte Fehlernummer des + zuletzt ausgeführten LDAP Kommandos für die angegebene + Vebindungs-Kennung. Diese Nummer kann mit der Funktion <function> + ldap_err2str</function> in einen Fehlertext konvertiert werden. + </para> + <para> + Solange Sie die Stufe der Fehlerwarnungen in Ihrer php3.ini nicht + herabsetzen oder vor Ihre LDAP Komanndos ein @ (at) setzen + um die Ausgabe von Fehlermeldungen zu unterdrücken, werden die + aufgetretenen Fehler auch in Ihrer HTML Ausgabe zu sehen sein. + <example> + <title>Erzeugen und Abfangen eines Fehlers</title> +<programlisting role="php"> +&lt;?php +/* Diese Beispiel enhält einen Fehler, der abgefangen wird.*/ +$ld = ldap_connect("localhost"); +$bind = ldap_bind($ld); +// Syntax Fehler im Filterausdruck (errno 87), +// müsste "objectclass=*" heißen, um zu funktionieren. +$res = @ldap_search($ld, "o=Meine Firma, c=DE", "objectclass"); +if (!$res) { + printf("LDAP-Fehlernummer: %s&lt;br>\n", ldap_errno($ld)); + printf("LDAP-Fehler: %s&lt;br>\n", ldap_error($ld)); + die("Argh!&lt;br>\n"); +} +$info = ldap_get_entries($ld, $res); +printf("%d Übereinstimmende Einträge.&lt;br>\n", $info["count"]); +?> +</programlisting> + </example> + </para> + <para> + Siehe auch <function>ldap_err2str</function> und + <function>ldap_error</function>.</para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-error"> + <refnamediv> + <refname>ldap_error</refname> + <refpurpose> + Liefert die LDAP Fehlermeldung des letzten LDAP Kommandos + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ldap_error</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabe: Fehlertext</para> + <para> + Diese Funktion liefert den erklärenden Fehlertext für einen + Fehler, der vom zuletzt ausgeführten LDAP Kommando mit der + angegebenen Verbindungs-Kennung erzeugt wurde. + Während LDAP Fehlernummern standardisiert sind, liefern + unterschiedliche Bibliotheken unterschiedliche oder sogar + lokalspezifische Fehlermeldungen. Deshalb sollten Sie nie auf + eine spezielle Fehlermeldung prüfen, sondern immer eine + Fehlernummer verwenden. + </para> + <para> + Solange Sie die Stufe der Fehlerwarnungen in Ihrer php3.ini nicht + herabsetzen oder vor Ihre LDAP Komanndos ein @ (at) setzen + um die Ausgabe von Fehlermeldungen zu unterdrücken, werden die + aufgetretenen Fehler auch in Ihrer HTML Ausgabe zu sehen sein. + </para> + <para> + Siehe auch <function>ldap_err2str</function> und + <function>ldap_errno</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-explode-dn"> + <refnamediv> + <refname>ldap_explode_dn</refname> + <refpurpose> + Aufteilung eines DN in seine Bestandteile + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>ldap_explode_dn</function></funcdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>int <parameter>mit_merkmal</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Die <function>ldap_explode_dn</function> Funktion wird benutzt um + einen von <function>ldap_get_dn</function> gelieferten DN + aufzuteilen und in dessen Bestandteile zu zerlegen. Jeder Teil + wird als Relative Distinguished Name, RDN, bezeichnet. + <function>ldap_explode_dn</function> liefert einen Array mit + allen diesen Bestandteilen + Der Parameter <parameter>mit_merkmal</parameter> wird benutzt, um + zu bestimmen, ob die RDNs nur mit Werten oder zusätlich mit ihren + Merkmalen angefragt werden. Um RDNs mit Merkmalen (z.B. Merkmal= + Wert Format) zu erhalten, setzen Sie <parameter> + mit_merkmal</parameter> auf 0, um nur Werte zu erhalten auf 1. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-first-attribute"> + <refnamediv> + <refname>ldap_first_attribute</refname> + <refpurpose>Liefert das erste Merkmal</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ldap_first_attribute</function> + </funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>ber-Kennung</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall das erste Merkmal des Eintrags, im + Fehlerfall falsch. + </para> + <para> + Ähnlich wie Einträge lesen, Merkmale eines bestimmten Eintrags + werden eins nach dem anderen gelesen. + Die <function>ldap_first_attribute</function> Funktion liefert + das erste Merkmal eines Eintrags der durch Ergebnis-Eintrag- + Kennung angegeben wurde. Durch erfolgreichen Aufruf von + <function>ldap_next_attribute</function> erhalten Sie die + restlichen Merkmale. + Der Parameter <parameter>ber-Kennung</parameter> ist die Kennung + eines internen Speicherort-Zeiger. Die Übergabe erfolgt per + Referenz. Die gleiche <parameter>ber-Kennung</parameter> wird an + die Funktion <function>ldap_next_attribute</function> + weitergegeben, die diesen Zeiger dann verändert. + </para> + <para> + Siehe auch <function>ldap_get_attributes</function></para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-first-entry"> + <refnamediv> + <refname>ldap_first_entry</refname> + <refpurpose> + Liefert die Kennung des ersten Ergebnisses + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_first_entry</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall die Ergebnis-Eintrag-Kennung + für den ersten Eintrag, falsch im Fehlerfall. + </para> + <para> + Einträge eines LDAP Ergebnisses werden unter Verwendung der + Funktionen <function>ldap_first_entry</function> und + <function>ldap_next_entry</function> sequentiell gelesen. + Die <function>ldap_first_entry</function> Funktion gibt die + Eintrag-Kennung für den ersten Eintrag im Ergebnis zurück. + Diese Eintrag-Kennung wird dann an die Funktion <function> + lap_next_entry</function> weitergegeben, um sukzessiv die + Einträge des Ergebnisses zu erhalten. + </para> + <para> + Siehe auch <function>ldap_get_entries</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-free-result"> + <refnamediv> + <refname>ldap_free_result</refname> + <refpurpose> + Gibt den belegten Speicher wieder frei + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_free_result</function></funcdef> + <paramdef>int <parameter>Ergebnis-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Um die Ergebnisse zu speichern, wird intern Speicher belegt. + Diesen Speicher können Sie mit der Funktion <function> + ldap_free_result</function> unter Angabe der entsprechenden + <parameter>Ergebnis-Kennung</parameter> wieder freigeben. + Typischerweise wird nach Beendigung des Skripts der gesamte + Ergebnis-Speicher automatisch freigegeben. + </para> + <para> + Falls Ihr Skript sukzessive Suchoperationen durchführt, die + große Ergebnismengen liefern, können Sie <function> + ldap_free_result</function> benutzen, um den Speicherverbrauch + zur Laufzeit niedrig zu halten. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-get-attributes"> + <refnamediv> + <refname>ldap_get_attributes</refname> + <refpurpose> + Liefert Merkmale eines Suchergebnis-Eintrags + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>ldap_get_attributes</function> + </funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int + <parameter>Ergebnis-Eintrag-Kennung</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall wird die gesamte Information eines + Eintrags in einem multidimensionalen Array zurückgegeben; im + Fehlerfall falsch. + </para> + <para> + Die <function>ldap_get_attributes</function> Funktion + wird verwendet um das Lesen der Merkmale und Werte eines Eintrags + im Suchergebnis zu vereinfachen. Der Rückgabewert ist ein + multidimensionales Array aus Merkmalen und Werten. + </para> + <para> + Nachdem Sie einen bestimmten Eintrag in dem Verzeichnis + lokalisiert haben, können Sie mit dieser Funktion herausfinden, + welche Informationen für diesen Eintrag verfügbar sind. Diese + Funktion würden Sie in einer Anwendung verwenden, die + Verzeichniseinträge "durchstöbert" und/oder wo Sie die Struktur + der Verzeichniseinträge nicht kennen. In vielen Anwendungen + suchen Sie nach einem bestimmten Merkmal wie einer email- + Adresse oder einem Nachnamen und interessieren sich nicht dafür, + welche anderen Daten verfügbar sind. + </para> + <para> + <informalexample><literallayout> +return_value["count"] = Anzahl der Merkmale des Eintrags +return_value[0] = das erste Merkmal +return_value[n] = das n-te Merkmal + +return_value["merkmal"]["count"] = Anzahl der Werte des Merkmals +return_value["merkmal"][0] = der erste Wert des Merkmals +return_value["merkmal"][i] = der i-te Wert des Merkmals +</literallayout></informalexample> + + <example> + <title> + Anzeigen der Liste der Merkmale für einen ausgewählten + Verzeichnis-Eintrag + </title> +<programlisting role="php"> +// $ds die Verbindungs-Kennung für das Verzeichnis + +// $sr ein gültiges Suchergebnis eines früheren Aufrufs einer der ldap +// Verzeichnis Suchfunktionen + + +$entry = ldap_first_entry($ds, $sr); + +$attrs = ldap_get_attributes($ds, $entry); + +echo $attrs["count"]." Merkmale für diesen Eintrag:&lt;p>"; + +for ($i=0; $i&lt;$attrs["count"]; $i++) + echo $attrs[$i]."&lt;br>"; +</programlisting> +</example></para> + + <para> + Siehe auch <function>ldap_first_attribute</function> und + <function>ldap_next_attribute</function></para> + + </refsect1> + </refentry> + + + <refentry id="function.ldap-get-dn"> + <refnamediv> + <refname>ldap_get_dn</refname> + <refpurpose>Liefert den DN eines Ergebnis-Eintrags </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ldap_get_dn</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall der DN des Ergebnis-Eintrags, im + Fehlerfall falsch. + </para> + <para> + Die <function>ldap_get_dn</function> Funktion wird verwendet, um + den DN eines Eintrags im Ergebnis herauszufinden. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-get-entries"> + <refnamediv> + <refname>ldap_get_entries</refname> + <refpurpose>Liefert alle Ergebnis-Einträge</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>ldap_get_entries</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall wird die gesamte Information des + Ergebnisses in einem multidimensionalen Array zurückgegeben; im + Fehlerfall falsch. + </para> + <para> + Die <function>ldap_get_entries</function> Funktion wird verwendet + um das Lesen mehrfacher Einträge des Ergebnisses zu vereinfachen + und danach werden die Merkmale und mehfachen Werte gelesen. + Durch einen Funktionsaufruf wird die gesamte Information in einem + multidimensionalen Array zurückgegeben. Die Struktur dieses Array + sieht wie folgt aus. + </para> + <para> + Der Merkmal-Index wird in Kleinbuchstaben umgewandelt. + (Verzeichnis-Server unterscheiden nicht zwischen + Groß-/Kleinschreibung hinsichtlich der Merkmake, aber der + Unterschied ist wichtig, wenn diese Merkmale als Array-Indizes + benutzt werden.) + + <informalexample> +<literallayout> +return_value["count"] = Anzahl der Merkmale im Ergebnis +return_value[0] : bezieht sich auf Einzelheiten des ersten + Eintrags + +return_value[i]["dn"] = DN des i-ten Eintrags im Ergebnis + +return_value[i]["count"] = Anzahl der Merkmale im i-ten Eintrag +return_value[i][j] = das j-te Merkmal des i-ten Eintrags im Ergebnis + +return_value[i]["merkmal"]["count"] = Anzahl der Werte für das + Merkmal im i-ten Eintrag +return_value[i]["merkmal"][j] = der j-te Wert des Merkmals im i-ten + Eintrag +</literallayout> + </informalexample> + </para> + + <para> + Siehe auch <function>ldap_first_entry</function> und + <function>ldap_next_entry</function></para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-get-option"> + <refnamediv> + <refname>ldap_get_option</refname> + <refpurpose> + Liefert den aktuellen Wert für eine gegebene Option + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>ldap_get_option</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>option</parameter></paramdef> + <paramdef>mixed <parameter>retval</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Setzt <parameter>retval</parameter> auf den Wert der gewählten + Option. + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Der Parameter <parameter>option</parameter> kann einer der + folgenden sein: + LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, + LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, + LDAP_OPT_REFERRALS, + LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING, + LDAP_OPT_MATCHED_DN. Beschrieben sind diese unter + <ulink url="&url.ldap.openldap-c-api;">draft-ietf-ldapext-ldap-c- + api-xx.txt</ulink> + </para> + <para> + Diese Funktion steht nur zur Verfügung, wenn Sie OpenLDAP 2.x.x + ODER Netscape Directory SDK x.x benutzen. + Wurde in PHP 4.0.4 hinzugefügt. + </para> + + <para> + <example> + <title>Prüfen der Protokollversion</title> +<programlisting role="php"> +// $ds eine gültige Verbindungs-Kennung für einen Verzeichnis-Server +if (ldap_get_option($ds, LDAP_OPT_PROTOCOL_VERSION, $version)) + echo "Sie benutzen die Protokollversion $version"; +else + echo "Protokollversion konnte nicht bestimmt werden"; +</programlisting> + </example> + </para> + + <para> + Siehe auch <function>ldap_set_option</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-get-values"> + <refnamediv> + <refname>ldap_get_values</refname> + <refpurpose> + Liefert alle Werte eines Ergebnis-Eintrags + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>ldap_get_values</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>merkmal</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall ein Array der Werte des Merkmals, + falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_get_values</function> Funktion wird benutzt um + alle Werte des Merkmals eines Eintrags im Ergebnis zu lesen. Der + Eintrag wird durch + <parameter>Ergebnis-Eintrag-Kennung</parameter> bestimmt. Die + Anzahl der Werte kann über die + Indexierung von "count" des resultierenden Arrays bestimmt + werden. Der Zugriff auf einzelne Werte erfolgt durch einen + ganzzahligen Index im Array. Der erste Indexwert ist 0. + </para> + <para> + Da diese Funktion eine + <parameter>Ergebnis-Eintrag-Kennung</parameter> benötigt, muss + ein Aufruf einer der LDAP Suchfunktionen und einer der + Funktionen, die einen einzelnen Eintrag liefern, vorausgehen. + </para> + <para> + Ihre Anwendung wird entweder hart codiert sein, um bestimmte + Merkmale (wie z.B.: "Nachname" oder "Mail") zu suchen, oder Sie + müssen die Funktion <function>ldap_get_attributes</function> + benutzen, um herauszufinden, welche Merkmale für einen gegebenen + Eintrag vorhanden sind. + </para> + <para> + LDAP erlaubt mehr als einen Eintrag für ein Merkmal, so daß es + z.B. sein kann, dass der Verzeichnis-Eintrag einer Person mehrere + Email-Adressen enthält, die alle mit dem Merkmal "mail" + bezeichnet sind. + + <informalexample> +<literallayout> +return_value["count"] = Anzahl der Werte eines Merkmals +return_value[0] = der erste Wert des Merkmals +return_value[i] = der i-te Wert des Merkmals +</literallayout> + </informalexample> + + <example> + <title> + Liste aller Werte des Merkmals "mail" für einen Verzeichnis- + Eintrag + </title> +<programlisting role="php"> +// $ds eine gültige Verbindungs-Kennung für einen Verzeichnis-Server + +// $sr ein gültiges Suchergebnis eines früheren Aufrufs einer der ldap +// Verzeichnis Suchfunktionen + +// $entry eine gültige Eintrag-Kennung eines früheren Aufrufs einer +// der Funktionen, die einen Verzeichnis-Eintrag zurückgeben + +$values = ldap_get_values($ds, $entry,"mail"); + +echo $values["count"]." Email-Adressen für diesen Eintrag.&lt;p>"; + +for ($i=0; $i &lt; $values["count"]; $i++) + echo $values[$i]."&lt;br>"; +</programlisting> + </example></para> + + </refsect1> + </refentry> + + + <refentry id="function.ldap-get-values-len"> + <refnamediv> + <refname>ldap_get_values_len</refname> + <refpurpose> + Liefert alle binären Werte eines Ergebnis-Eintrags + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>ldap_get_values_len</function> + </funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>merkmal</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall ein Array der Werte des Merkmals, + falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_get_values_len</function> Funktion wird + benutzt um alle Werte des Merkmals eines Eintrags im Ergebnis zu + lesen. Der Eintrag wird durch + <parameter>Ergebnis-Eintrag-Kennung</parameter> bestimmt. Die + Anzahl der Werte kann über die Indexierung von "count" des + resultierenden Arrays bestimmt werden. Der Zugriff auf einzelne + Werte erfolgt durch einen ganzzahligen Index im Array. Der erste + Indexwert ist 0. + </para> + <para> + Diese Funktion wird in der genau gleichen Weise benutzt wie die + Funktion <function>ldap_get_values</function> mit der Aussnahme, + dass hier binäre Daten statt Textdaten behandelt werden. + </para> + <note> + <para> + Diese Funktion wurde in 4.0 hinzugefügt. + </para> + </note> + </refsect1> + </refentry> + + + <refentry id="function.ldap-list"> + <refnamediv> + <refname>ldap_list</refname> + <refpurpose>Einstufige Suche</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_list</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>basis_dn</parameter></paramdef> + <paramdef>string <parameter>filter</parameter></paramdef> + <paramdef>array + <parameter><optional>merkmale</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>attrsonly</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>größenbegrenzung</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>zeitbegrenzung</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>deref</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall eine Such-Ergebnis-Kennung,im + Fehlerfall falsch. + </para> + <para> + Die <function>ldap_list</function> Funktion führt die Suche für + einen gegebenen Filter im Verzeichnis mit der Reichweite von + LDAP_SCOPE_ONELEVEL durch. + </para> + <para> + LDAP_SCOPE_ONELEVEL bedeutet, dass die Suche nur Informationen + liefert, die direkt unterhalb der Stufe liegen, die durch die + Angabe des Basis dn im Auruf bestimmt wird. (Das entspricht der + Eingabe von "ls", die eine Liste von Dateien und Verzeichnissen + des aktuellen Arbeitsverzeichnisses anzeigt.) + </para> + <para> + Der Aufruf dieser Funktion nimmt 5 optionale Parameter entgegen. + Siehe die Anmerkungen zu <function>ldap_search</function>. + <note> + <para> + Diese wahlfreien Parameter wurden in 4.0.2 hinzugefügt: + <parameter>attrsonly</parameter>, + <parameter>größenbegrenzung</parameter>, + <parameter>zeitbegrenzung</parameter>, + <parameter>deref</parameter>. + </para> + </note> + + <example> + <title> + Erzeugung einer Liste aller Organisationseinheiten einer + Organisation + </title> +<programlisting role="php3"> +// $ds gültige Verbindungs-Kennung für einen Verzeichnis-Server + +$basis_dn = "o=Meine Firma, c=DE"; +$nur_dieses = array("ou"); + +$sr=ldap_list($ds, $basis_dn, "ou=*", $nur_dieses); + +$info = ldap_get_entries($ds, $sr); + +for ($i=0; $i&lt;$info["count"]; $i++) + echo $info[$i]["ou"][0] ; +</programlisting> +</example></para> + <para> + Seit der Version 4.0.5 ist es außerdem möglich parallele Suchen + durchzuführen. Für Details siehe + <function>ldap_search</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-modify"> + <refnamediv> + <refname>ldap_modify</refname> + <refpurpose>Verändern eines LDAP-Eintrags</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_modify</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>array <parameter>eintrag</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_modify</function> Funktion wird verwendet, um + bestehende Einträge in einem LDAP-Verzeichnis zu ändern. + Die Struktur des Eintrags ist die gleiche wie bei <function> + ldap_add</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-mod-add"> + <refnamediv> + <refname>ldap_mod_add</refname> + <refpurpose> + Hinzufügen von Merkmalswerten zu aktuellen Merkmalen + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_mod_add</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>array <parameter>eintrag</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Diese Funktion fügt Merkmal(e) zum angegebenen dn hinzu. + Die Änderung wird auf der Merkmalsebene durchgeführt im + Gegensatz zur Objektebene. Das Hinzufügen auf der Objektebene + wird durch die Funktion <function>ldap_add</function> geleistet. + </para> + </refsect1> + </refentry> + + <refentry id="function.ldap-mod-del"> + <refnamediv> + <refname>ldap_mod_del</refname> + <refpurpose> + Löschen von Merkmalswerten aktueller Merkmale + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_mod_del</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>array <parameter>eintrag</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Diese Funktion entfernt ein oder mehrere Merkmale vom angegebenen + dn. Die Änderung wird auf der Merkmalsebene durchgeführt im + Gegensatz zur Objektebene. Das Löschen auf Objektebene wird + durch die Funktion <function>ldap_delete</function> geleistet. + </para> + </refsect1> + </refentry> + + <refentry id="function.ldap-mod-replace"> + <refnamediv> + <refname>ldap_mod_replace</refname> + <refpurpose> + Ersetzen von Merkmalswerten mit neuen Merkmalswerten + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_mod_replace</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>array <parameter>eintrag</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Diese Funktion ersetzt ein oder mehrere Merkmale vom angegebenen + dn. Die Änderung wird auf der Merkmalsebene durchgeführt im + Gegensatz zur Objektebene. Änderungen auf der Objektebene wird + durch die Funktion <function>ldap_modify</function> geleistet. + </para> + </refsect1> + </refentry> + + <refentry id="function.ldap-next-attribute"> + <refnamediv> + <refname>ldap_next_attribute</refname> + <refpurpose> + Liefert das nächste Merkmal im Ergebnis + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ldap_next_attribute</function> + </funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>ber_Kennung</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: im Erfolgsfall das nächste Merkmal eines Eintrags, + im Fehlerfall falsch. + </para> + <para> + Die <function>ldap_next_attribute</function> Funktion wird + aufgerufen, um die Merkmale eines Eintrags zu erhalten. Der + interne Status des Zeigers wird durch die <parameter> + ber_Kennung</parameter> bestimmt. Diese wird mittels Referenz an + die Funktion weitergegeben. + Der erste Aufruf von <function>ldap_next_attribute</function> + erfolgt mit der <parameter>Ergebnis-Eintrag-Kennung</parameter>, + die von <function>ldap_first_attribute</function> zurückgegeben + wurde. + </para> + <para> + Siehe auch <function>ldap_get_attributes</function> + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-next-entry"> + <refnamediv> + <refname>ldap_next_entry</refname> + <refpurpose> + Liefert den nächsten Eintrag des Ergebnisses + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_next_entry</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>Ergebnis-Eintrag-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: Im Erfolgsfall wird die Eintrags-Kennung für den + nächsten Eintrag des Ergebnisses zurückgegeben. Das Lesen der + Einträge wird mit <function>ldap_first_entry</function> + gestartet. + Wenn keine weiteren Einträge im Ergebnis vorhanden sind wird + falsch zurückgegeben. + </para> + <para> + Die <function>ldap_next_entry</function> Funktion wird verwendet, + um die Einträge zu erhalten, die im Ergebnis gespeichert sind. + Wiederholtes aufrufen von <function>ldap_next_entry</function> + liefert einen Eintrag nach dem anderen, solange bis kein Eintrag + mehr vorliegt. Der erste Aufruf von <function> + ldap_next_entry</function> erfolgt nach dem Aufruf von + <function>ldap_first_entry</function> mit der Ergebnis-Kennung, + die von <function>ldap_first_entry</function> zurückgegeben + wurde. + </para> + <para> + Siehe auch <function>ldap_get_entries</function> + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-read"> + <refnamediv> + <refname>ldap_read</refname> + <refpurpose>Lesen eines Eintrags</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_read</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>basis_dn</parameter></paramdef> + <paramdef>string <parameter>filter</parameter></paramdef> + <paramdef>array + <parameter><optional>merkmale</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>attrsonly</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>größenbegrenzung</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>zeitbegrenzung</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>deref</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: Im Erfolgsfall eine Such-Ergebnis-Kennung, falsch + im Fehlerfall. + </para> + <para> + Die <function>ldap_read</function> Funktion führt die Suche für + einen gegebenen Filter im Verzeichnis mit der Reichweite von + LDAP_SCOPE_BASE durch. Das ist äquivalent zum Lesen eines + Eintrags in einem Verzeichnis. + </para> + <para> + Ein leerer Filter ist nicht erlaubt. Wenn Sie wirklich alle + Informationen für einen Eintrag erhalten möchten, müssen Sie + einen Filter der Art "objectClass=*" verwenden. Kennen Sie die + Typen der Einträge die auf dem Verzeichnis-Server benutzt werden, + können Sie einen passenden Filter wie z.B."objectClass= + inetOrgPerson" verwenden. + </para> + <para> + Der Aufruf dieser Funktion nimmt 5 optionale Argumente + entgegen. Siehe Anmerkungen zu <function>ldap_search</function>. + </para> + <note> + <para> + Diese wahlfreien Argumente wurden in 4.0.2 hinzugefügt: + <parameter>attrsonly</parameter>, + <parameter>größenbegrenzung</parameter>, + <parameter>zeitbegrenzung</parameter>, + <parameter>deref</parameter>. + </para> + </note> + <para> + Seit der Version 4.0.5 ist es außerdem möglich parallele Suchen + durchzuführen. Für Details siehe + <function>ldap_search</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-rename"> + <refnamediv> + <refname>ldap_rename</refname> + <refpurpose> + Verändert den Namen eines Eintrags + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>ldap_rename</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>dn</parameter></paramdef> + <paramdef>string <parameter>neuerrdn</parameter></paramdef> + <paramdef>string <parameter>neueeltern</parameter></paramdef> + <paramdef>bool <parameter>löschealtenrdn</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Der Eintrag, der durch <parameter>dn</parameter> gegeben ist, + wird umbenannt/enfernt. Der neue RDN wird durch <parameter> + neuerrdn</parameter> bestimmt, der neue Eltern-/übergeordnete + Eintrag wird durch <parameter>neueeltern</parameter> bestimmt. + Wenn das Argument <parameter>löschealtenrdn</parameter> wahr ist, + wird der alte Wert/die alten Werte von RDN enfernt, andernfalls + wird der alte Wert/die alten Werte als nicht-eindeutige (non- + distinguished) Werte des Eintrags beibehalten. + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Diese Funktion steht nur zur Verfügung, wenn Sie OpenLDAP 2.x.x + ODER Netscape Directory SDK x.x benutzen. Wurde in PHP 4.0.5 + hinzugefügt. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-search"> + <refnamediv> + <refname>ldap_search</refname> + <refpurpose>Suche im LDAP Baum</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_search</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>string <parameter>base_dn</parameter></paramdef> + <paramdef>string <parameter>filter</parameter></paramdef> + <paramdef>array + <parameter><optional>merkmale</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>attrsonly</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>größenbegrenzung</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>zeitbegrenzung</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>deref</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: eine Such-Ergebnis-Kennung im Erfolgsfall, falsch + im Fehlerfall. + </para> + <para> + Die <function>ldap_search</function> Funktion führt die Suche für + einen gegebenen Filter im Verzeichnis mit der Reichweite von + LDAP_SCOPE_SUBTREE durch. Das ist äquivalent zu einer Suche im + ganzen Verzeichnis.<parameter>base_dn</parameter> legt den Basis + DN für das Verzeichnis fest. + </para> + <para> + Der optionale vierte Parameter kann benutzt werden, um die + Rückgabewerte des Servers so einzuschränken, dass nur die + tatsächlich benötigten Merkmale und ihre zugehörigen Werte in der + Ergebnismenge enthalten sind. Dieses Vorgehen ist um einiges + effizienter als die standardmäßige Vorgehensweise (diese liefert + alle Merkmale und alle zugehörigen Werte). Aus diesem Grund ist + die Angabe des vierten Parameters als gute Praxis zu empfehlen. + </para> + <para> + Der vierte Parameter ist ein Standard PHP Zeichenketten Array der + benötigten Merkmale, z.B. array("mail","sn","cn"). Beachten Sie, + dass der DN immer zurückgeliefert wird, ohne Rücksicht darauf, + welche Merkmalstypen angefragt wurden. + </para> + <para> + Beachten Sie weiterhin, dass manche Verzeichnis-Server so + konfiguriert sind, dass sie nicht mehr als eine vorbestimmte + Anzahl an Einträgen zurückliefern. Sollte dies der Fall sein, + zeigt Ihnen der Server an, dass nur eine Teilmenge des + Ergebnisses zurückgeliefert wurde. Diesen Hinweis erhalten Sie + auch, wenn Sie den sechsten Parameter + <parameter>größenbegrenzung</parameter> mit angegeben hatten, um + die Anzahl der angefragten Einträge einzuschränken. + </para> + <para> + Der fünfte Parameter <parameter>attrsonly</parameter> sollte auf + 1 gesetzt werden, wenn Sie nur Merkmalstypen erhalten möchten. + Wenn der Wert auf 0 steht, erhalten Sie sowohl Merkmalstypen als + auch Merkmalswerte. Das ist das Standard Verhalten. + </para> + <para> + Mit dem sechsten Parameter + <parameter>größenbegrenzung</parameter> ist es möglich, die + Anzahl der Einträge, die Sie erhalten, zu begrenzen. + Wenn Sie diesen Wert auf 0 setzen, bedeutet dies keine + Beschränkung der Ergegnismenge. + ANMERKUNG: Dieser Parameter kann eine serverseitig gesetzte + Beschränkung NICHT überschreiben. Sie haben nur die Möglichkeit + die Beschränkung noch weiter herabzusetzen. + </para> + <para> + Der siebte Parameter <parameter>zeitbegrenzung</parameter> legt + die Zahl in Sekunden fest, die auf die Suche verwendet wird. + Wenn Sie diesen Wert auf 0 setzen, bedeutet dies keine + Beschränkung der Zeit. + ANMERKUNG: Dieser Parameter kann eine serverseitig gesetzte + Zeitbegrenzung NICHT überschreiben. Sie haben nur die + Möglichkeit die Beschränkung noch weiter herabzusetzen. + </para> + <para> + Der achte Parameter <parameter>deref</parameter> gibt an, wie + Aliase während einer Suche behandelt werden. + Wert kann einer der folgenden sein: + <itemizedlist> + <listitem> + <simpara> + LDAP_DEREF_NEVER - (Standard) Aliase werden nie aufgelöst. + </simpara> + </listitem> + <listitem> + <simpara> + LDAP_DEREF_SEARCHING - Aliase sollen während der Suche + aufgelöst werden, aber nicht dann, wenn das Basisobjekt der + Suche ermittelt wird. + </simpara> + </listitem> + <listitem> + <simpara> + LDAP_DEREF_FINDING - Aliase sollen aufgelöst werden, wenn das + Basisobjekt ermiitelt wird, aber nicht während der Suche. + </simpara> + </listitem> + <listitem> + <simpara> + LDAP_DEREF_ALWAYS - Aliase sollen immer aufgelöst werden. + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + Diese optionalen Parameter wurden in 4.0.2 hinzugefügt: + <parameter>attrsonly</parameter>, + <parameter>größenbegrenzung</parameter>, + <parameter>zeitbegrenzung</parameter>, + <parameter>deref</parameter>. + </para> + <para> + Der Suchfilter kann einfach oder komplizierter sein, wenn sie + boolsche Operatoren in dem Format verwenden, wie in der LDAP + Dokumentation beschrieben (siehe <ulink url="&url.ldap.filters;"> + Netscape Directory SDK</ulink> für die vollständige Information + über Filter). + </para> + <para> + Das untenstehende Beispiel liefert die Organisationseinheit, den + Familiennamen, den Vornamen und die Email-Addresse aller Personen + in "Meine Firma" deren Familien- oder Vorname die Zeichenkette + $person enhält. In diesem Beispiel wird ein boolscher Filter + verwendet, um den Server zu veranlassen, nach Informationen in + mehr als einem Merkmal zu suchen. + + <example> + <title>LDAP Suche</title> +<programlisting role="php"> +// $ds gültige Verbindungs-Kennung für einen Verzeichnis-Server + +// $person ein Teil oder der vollständige Name einer Person, z.B. + "Jo" + +$dn = "o=Meine Firma, c=DE"; +$filter="(|(sn=$person*)(vorname=$person*))"; +$justthese = array( "ou", "sn", "vorname", "mail"); + +$sr=ldap_search($ds, $dn, $filter, $justthese); + +$info = ldap_get_entries($ds, $sr); + +print $info["count"]." gefundene Einträge&lt;p>"; +</programlisting> + </example> + </para> + <para> + Seit der Version 4.0.5 ist es außerdem möglich parallele Suchen + durchzuführen. Um dies zu verwirklichen benutzen Sie als erstes + Argument einen Array von Verbindungs-Kennungen, statt einer + einzelnen Verbindungs-Kennung. Falls Sie nicht den gleichen Basis + DN und den gleichen Filter für alle Suchen verwenden möchten, + können Sie ebenso einen Array von Basis DNs und/oder einen Array + von Filtern benutzen. Diese Arrays müssen die gleiche Größe wie + das Array der Verbindungs-Kennungen haben, da die ersten Einträge + der Arrays für eine Suche verwendet werden, die zweiten Einträge + für eine andere Suche und so weiter. Wenn Sie parallel suchen + erhalten Sie ein Array von Such-Ergebnis-Kennungen, außer im Fall + eines Fehlers, dann liefert der Eintrag zur entsprechenden Suche + falsch zurück. Das entspricht ganz genau dem Wert der + normalerweise zurückgeliefert wird, außer dass Sie immer eine + Ergebnis-Kennung erhalten, wenn Sie eine Suche durchgeführt + haben. Es treten einige seltene Fälle auf, wo eine normale Suche + falsch zurückgibt, während die parallele Suche eine Kennung + zurückliefert. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-set-option"> + <refnamediv> + <refname>ldap_set_option</refname> + <refpurpose>Setzt den Wert der gegebenen Option</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>ldap_set_option</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + <paramdef>int <parameter>option</parameter></paramdef> + <paramdef>mixed <parameter>neuerwert</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Setzt den Wert der bestimmten Option auf + <parameter>neuerwert</parameter>. + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Der Parameter <parameter>option</parameter> kann einer der + folgenden sein: + LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, + LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, + LDAP_OPT_REFERRALS, + LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING, + LDAP_OPT_MATCHED_DN, LDAP_OPT_SERVER_CONTROLS, + LDAP_OPT_CLIENT_CONTROLS. + Hier eine kurze Beschreibung, schauen Sie unter + <ulink url="&url.ldap.openldap-c-api;">draft-ietf-ldapext-ldap-c- + api-xx.txt</ulink> nach Details. + </para> + <para> + Die Optionen LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, + LDAP_OPT_TIMELIMIT, LDAP_OPT_PROTOCOL_VERSION und + LDAP_OPT_ERROR_NUMBER haben einen ganzzahligen Wert, + LDAP_OPT_REFERRALS und LDAP_OPT_RESTART haben einen boolschen + Wert und die Optionen LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING + und LDAP_OPT_MATCHED_DN bestehen aus einer Zeichenkette. + Das erste Beispiel veranschaulicht deren Gebrauch. Die Optionen + LDAP_OPT_SERVER_CONTROLS and LDAP_OPT_CLIENT_CONTROLS benötigen + eine Kontrolliste, d.h. der Wert muss ein Array aus Kontrollen + sein. Eine Kontrolle besteht aus einer <emphasis>oid</emphasis> + die die Kontrolle identifiziert, einem wahlweisen <emphasis> + wert</emphasis>, und einem wahlweisen Kennzeichen für <emphasis> + criticality</emphasis>. Bei PHP wird eine Kontrolle durch ein + Array angegeben. Dieses Array enthält ein Element mit dem + Schlüssel <emphasis>oid</emphasis> und einer Zeichenkette als + Wert und zwei optionalen Elementen. Die optionalen Elemente sind + Schlüssel <emphasis>wert</emphasis> mit einer Zeichenkette als + Wert und dem Schlüssel <emphasis>iscritical</emphasis> mit einem + boolschen Wert. Der vorgegebene Wert von <emphasis> + iscritical</emphasis> ist <emphasis>&false;</emphasis> falls Sie + nichts angeben. + Schauen Sie sich das zweite Beispiel weiter unten an. + </para> + <para> + Diese Funktion steht nur zur Verfügung, wenn Sie OpenLDAP 2.x.x + ODER Netscape Directory SDK x.x verwenden und wurde in PHP 4.0.4 + hinzugefügt. + </para> + <para> + <example> + <title>Setzen der Protokollversion</title> +<programlisting role="php"> +// $ds ist eine gültige Verbindungs-Kennung für einen Verzeichnis- +// Server +if (ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)) + echo "Verwenden von LDAPv3"; +else + echo "Kann das Protokoll nicht auf Version 3 setzen"; +</programlisting> + </example> + <example> + <title>Setzen der Server Kontrollen</title> +<programlisting role="php"> +// $ds ist eine gültige Verbingund-Kennung für einen Verzeichnis- +// Server +// Kontrolle ohne Wert +$ctrl1 = array("oid" => "1.2.752.58.10.1", "iscritical" => TRUE); +// iscritical hat den vorgegebenen Wert FALSE +$ctrl2 = array("oid" => "1.2.752.58.1.10", "value" => "magic"); +// Versuch, beide Kontrollen zu setzen +if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, +$ctrl2))) + echo "Kann die Server Kontrollen nicht setzen"; +</programlisting> + </example> + </para> + <para> + Siehe auch <function>ldap_get_option</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.ldap-unbind"> + <refnamediv> + <refname>ldap_unbind</refname> + <refpurpose>Unbind von einem LDAP Verzeichnis</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ldap_unbind</function></funcdef> + <paramdef>int <parameter>Verbindungs-Kennung</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Rückgabewert: wahr im Erfolgsfall, falsch im Fehlerfall. + </para> + <para> + Die <function>ldap_unbind</function> Funktion führt ein unbind + auf ein LDAP Verzeichnis aus. + </para> + </refsect1> + </refentry> + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Index: phpdoc/de/functions/vmailmgr.xml diff -u phpdoc/de/functions/vmailmgr.xml:1.5 phpdoc/de/functions/vmailmgr.xml:1.6 --- phpdoc/de/functions/vmailmgr.xml:1.5 Mon Aug 14 10:31:28 2000 +++ phpdoc/de/functions/vmailmgr.xml Sat Jul 7 19:11:20 2001 @@ -169,19 +169,19 @@ </reference> -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> \ No newline at end of file +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/de/functions/wddx.xml diff -u phpdoc/de/functions/wddx.xml:1.5 phpdoc/de/functions/wddx.xml:1.6 --- phpdoc/de/functions/wddx.xml:1.5 Sun Jun 3 17:59:12 2001 +++ phpdoc/de/functions/wddx.xml Sat Jul 7 19:11:21 2001 @@ -1,265 +1,265 @@ - <reference id="ref.wddx"> - <title>WDDX Funktionen</title> - <titleabbrev>WDDX</titleabbrev> - - <partintro> - <para> - Diese Funktionen arbeiten mit <ulink url="&url.wddx;">WDDX</ulink> zusammen.</para> - - <para> - Es ist zu beachten, dass alle Funktionen, die Variablen serialisieren, - immer das erste Element eines Arrays verwenden um festzustellen ob der - Array in einen Array oder eine 'Structure' serialisiert wird. - Wenn das erste Element eine String Schlüssel hat, dann wir er in eine - 'Structure' serialisiert, andernfalls in einen Array. - - <example> - <title>Einen einzelnen String serialisieren</title> - <programlisting role="php"> -&lt;?php -print wddx_serialize_value("PHP to WDDX packet example", "PHP packet"); -?&gt; - </programlisting> - </example></para> - - <para> - dieses Beispiel erzeugt: - <informalexample> - <programlisting role="php"> -&lt;wddxPacket version='0.9'&gt;&lt;header comment='PHP packet'/&gt;&lt;data&gt; -&lt;string&gt;PHP to WDDX packet example&lt;/string&gt;&lt;/data&gt;&lt;/wddxPacket&gt; - </programlisting> - </informalexample> - - <example> - <title>Die Verwendung von inkrementierenden Paketen</title> - <programlisting role="php"> -&lt;?php -$pi = 3.1415926; -$packet_id = wddx_packet_start("PHP"); -wddx_add_vars($packet_id, "pi"); - -/* So tun, als ob $cities aus einer Datenbank kommt ;-) */ -$cities = array("Austin", "Novato", "Seattle"); -wddx_add_vars($packet_id, "cities"); - -$packet = wddx_packet_end($packet_id); -print $packet; -?&gt; - </programlisting> - </example></para> - - <para> - Diese Beispiel wird erzeugen: - - <informalexample> - <programlisting role="php"> -&lt;wddxPacket version='0.9'&gt;&lt;header comment='PHP'/&gt;&lt;data&gt;&lt;struct&gt; -&lt;var name='pi'&gt;&lt;number&gt;3.1415926&lt;/number&gt;&lt;/var&gt;&lt;var name='cities'&gt; -&lt;array length='3'&gt;&lt;string&gt;Austin&lt;/string&gt;&lt;string&gt;Novato&lt;/string&gt; -&lt;string&gt;Seattle&lt;/string&gt;&lt;/array&gt;&lt;/var&gt;&lt;/struct&gt;&lt;/data&gt;&lt;/wddxPacket&gt; - </programlisting> - </informalexample></para> - - </partintro> - - <refentry id="function.wddx-serialize-value"> - <refnamediv> - <refname>wddx_serialize_value</refname> - <refpurpose>Serialisiert einen einzelnen Wert in ein WDDX Packet</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string - <function>wddx_serialize_value</function></funcdef> - <paramdef>mixed <parameter>wert</parameter></paramdef> - <paramdef>string - <parameter><optional>kommentar</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - - <para> - <function>wddx_serialize_value</function> wird verwendet, um - einen einzelnen Wert in ein WDDX Packet zu serialisieren. - Übergeben wird der Wert in <parameter>wert</parameter>, und ein - optionaler <parameter>kommentar</parameter> der im Header des - Packets angegeben wird und gibt das WDDX Paket zurück.</para> - - </refsect1> - </refentry> - - <refentry id="function.wddx-serialize-vars"> - <refnamediv> - <refname>wddx_serialize_vars</refname> - <refpurpose>Serialisiert variablen in WDDX Pakete</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>wddx_serialize_vars</function></funcdef> - <paramdef>mixed <parameter>var_name</parameter></paramdef> - <paramdef>mixed - <parameter><optional>...</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - - <para> - <function>wddx_serialize_vars</function> wird verwendet um ein - WDDX Paket mit einer 'Structure', das eine serialsierte Representation - der übergebenen Variablen.</para> - - <para> - <function>wddx_serialize_vars</function> übernimmt eine variable - Zahl an Argumenten. Jedes kann entweder eine String Benennung, eine - Variable oder ein Array, der Strings enthält, die die Variablen - benennen, oder einen weiteren Array, etc.</para> - - <para> - <example> - <title>wddx_serialize_vars example</title> - <programlisting> -&lt;?php -$a = 1; -$b = 5.5; -$c = array("blue", "orange", "violet"); -$d = "colors"; - -$clvars = array("c", "d"); -print wddx_serialize_vars("a", "b", $clvars); -?&gt; - </programlisting> - </example></para> - - <para> - Das obige Script erzeugt: - <programlisting> -&lt;wddxPacket version='0.9'&gt;&lt;header/&gt;&lt;data&gt;&lt;struct&gt;&lt;var name='a'&gt;&lt;number&gt;1&lt;/number&gt;&lt;/var&gt; -&lt;var name='b'&gt;&lt;number&gt;5.5&lt;/number&gt;&lt;/var&gt;&lt;var name='c'&gt;&lt;array length='3'&gt; -&lt;string&gt;blue&lt;/string&gt;&lt;string&gt;orange&lt;/string&gt;&lt;string&gt;violet&lt;/string&gt;&lt;/array&gt;&lt;/var&gt; -&lt;var name='d'&gt;&lt;string&gt;colors&lt;/string&gt;&lt;/var&gt;&lt;/struct&gt;&lt;/data&gt;&lt;/wddxPacket&gt; - </programlisting></para> - - </refsect1> - </refentry> - - <refentry id="function.wddx-packet-start"> - <refnamediv> - <refname>wddx_packet_start</refname> - <refpurpose>Beginnt ein neue WDDX Packet mit einer 'Structure' darin</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>wddx_packet_start</function></funcdef> - <paramdef>string - <parameter><optional>kommentar</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - - <para> - <function>wddx_packet_start</function> wird verwendet um ein neues - WDDX Paket beginnen um die Variablen nachhinein zu ergänzen. - Ein optionaler <parameter>kommentar</parameter> String kann angegeben werden. - Es wird eine Packet ID zurückgegeben, die in später in Funktionen - verwendet werden kann. Desweiteren wird automatisch 'Structure' - Definition erzeugt um die Variablen aufnehmen zu können.</para> - - </refsect1> - </refentry> - - <refentry id="function.wddx-packet-end"> - <refnamediv> - <refname>wddx_packet_end</refname> - <refpurpose>Schliesst das WDDX Packet mit der angegebenen ID</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>wddx_packet_end</function></funcdef> - <paramdef>int <parameter>packet_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - - <para> - <function>wddx_packet_end</function> schliesst das WDDX Packet, - dass mit mit <parameter>packet_id</parameter> identifiziert wird - und gibt einen String mit dem Packet zurück.</para> - - </refsect1> - </refentry> - - <refentry id="function.wddx-add-vars"> - <refnamediv> - <refname>wddx_add_vars</refname> - <refpurpose>Fügt dem WDDX Packet mit der ID Werte hinzu</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef><function>wddx_add_vars</function></funcdef> - <paramdef>int <parameter>packet_id</parameter></paramdef> - <paramdef>mixed <parameter>name_var</parameter></paramdef> - <paramdef>mixed - <parameter><optional>...</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - - <para> - <function>wddx_add_vars</function> wird verwendet um die übergebenen - Werte zu serialisiern und diese an das Packet anzuhängen, das mit - <parameter>packet_id</parameter> identifiziert wird. - Die Werteübergabe funktioniert genauso wie bei - <function>wddx_serialize_vars</function>.</para> - - </refsect1> - </refentry> - - <refentry id="function.wddx-deserialize"> - <refnamediv> - <refname>wddx_deserialize</refname> - <refpurpose>Deserialisiert ein WDDX Packet</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>wddx_deserialize</function></funcdef> - <paramdef>string <parameter>packet</parameter></paramdef> - </funcprototype> - </funcsynopsis> - - <para> - <function>wddx_deserialized</function> übernimmt einen - <parameter>packet</parameter> String and deserialisiert es. - Es wird entweder ein String, eine Nummer, oder Array als Ergebnis - zurückgegeben. 'Structures' werden in assoziative Arrays - deserialisiert.</para> - - </refsect1> - </refentry> - </reference> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> \ No newline at end of file + <reference id="ref.wddx"> + <title>WDDX Funktionen</title> + <titleabbrev>WDDX</titleabbrev> + + <partintro> + <para> + Diese Funktionen arbeiten mit <ulink url="&url.wddx;">WDDX</ulink> zusammen.</para> + + <para> + Es ist zu beachten, dass alle Funktionen, die Variablen serialisieren, + immer das erste Element eines Arrays verwenden um festzustellen ob der + Array in einen Array oder eine 'Structure' serialisiert wird. + Wenn das erste Element eine String Schlüssel hat, dann wir er in eine + 'Structure' serialisiert, andernfalls in einen Array. + + <example> + <title>Einen einzelnen String serialisieren</title> + <programlisting role="php"> +&lt;?php +print wddx_serialize_value("PHP to WDDX packet example", "PHP packet"); +?&gt; + </programlisting> + </example></para> + + <para> + dieses Beispiel erzeugt: + <informalexample> + <programlisting role="php"> +&lt;wddxPacket version='0.9'&gt;&lt;header comment='PHP packet'/&gt;&lt;data&gt; +&lt;string&gt;PHP to WDDX packet example&lt;/string&gt;&lt;/data&gt;&lt;/wddxPacket&gt; + </programlisting> + </informalexample> + + <example> + <title>Die Verwendung von inkrementierenden Paketen</title> + <programlisting role="php"> +&lt;?php +$pi = 3.1415926; +$packet_id = wddx_packet_start("PHP"); +wddx_add_vars($packet_id, "pi"); + +/* So tun, als ob $cities aus einer Datenbank kommt ;-) */ +$cities = array("Austin", "Novato", "Seattle"); +wddx_add_vars($packet_id, "cities"); + +$packet = wddx_packet_end($packet_id); +print $packet; +?&gt; + </programlisting> + </example></para> + + <para> + Diese Beispiel wird erzeugen: + + <informalexample> + <programlisting role="php"> +&lt;wddxPacket version='0.9'&gt;&lt;header comment='PHP'/&gt;&lt;data&gt;&lt;struct&gt; +&lt;var name='pi'&gt;&lt;number&gt;3.1415926&lt;/number&gt;&lt;/var&gt;&lt;var name='cities'&gt; +&lt;array length='3'&gt;&lt;string&gt;Austin&lt;/string&gt;&lt;string&gt;Novato&lt;/string&gt; +&lt;string&gt;Seattle&lt;/string&gt;&lt;/array&gt;&lt;/var&gt;&lt;/struct&gt;&lt;/data&gt;&lt;/wddxPacket&gt; + </programlisting> + </informalexample></para> + + </partintro> + + <refentry id="function.wddx-serialize-value"> + <refnamediv> + <refname>wddx_serialize_value</refname> + <refpurpose>Serialisiert einen einzelnen Wert in ein WDDX Packet</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string + <function>wddx_serialize_value</function></funcdef> + <paramdef>mixed <parameter>wert</parameter></paramdef> + <paramdef>string + <parameter><optional>kommentar</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <function>wddx_serialize_value</function> wird verwendet, um + einen einzelnen Wert in ein WDDX Packet zu serialisieren. + Übergeben wird der Wert in <parameter>wert</parameter>, und ein + optionaler <parameter>kommentar</parameter> der im Header des + Packets angegeben wird und gibt das WDDX Paket zurück.</para> + + </refsect1> + </refentry> + + <refentry id="function.wddx-serialize-vars"> + <refnamediv> + <refname>wddx_serialize_vars</refname> + <refpurpose>Serialisiert variablen in WDDX Pakete</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>wddx_serialize_vars</function></funcdef> + <paramdef>mixed <parameter>var_name</parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <function>wddx_serialize_vars</function> wird verwendet um ein + WDDX Paket mit einer 'Structure', das eine serialsierte Representation + der übergebenen Variablen.</para> + + <para> + <function>wddx_serialize_vars</function> übernimmt eine variable + Zahl an Argumenten. Jedes kann entweder eine String Benennung, eine + Variable oder ein Array, der Strings enthält, die die Variablen + benennen, oder einen weiteren Array, etc.</para> + + <para> + <example> + <title>wddx_serialize_vars example</title> + <programlisting> +&lt;?php +$a = 1; +$b = 5.5; +$c = array("blue", "orange", "violet"); +$d = "colors"; + +$clvars = array("c", "d"); +print wddx_serialize_vars("a", "b", $clvars); +?&gt; + </programlisting> + </example></para> + + <para> + Das obige Script erzeugt: + <programlisting> +&lt;wddxPacket version='0.9'&gt;&lt;header/&gt;&lt;data&gt;&lt;struct&gt;&lt;var name='a'&gt;&lt;number&gt;1&lt;/number&gt;&lt;/var&gt; +&lt;var name='b'&gt;&lt;number&gt;5.5&lt;/number&gt;&lt;/var&gt;&lt;var name='c'&gt;&lt;array length='3'&gt; +&lt;string&gt;blue&lt;/string&gt;&lt;string&gt;orange&lt;/string&gt;&lt;string&gt;violet&lt;/string&gt;&lt;/array&gt;&lt;/var&gt; +&lt;var name='d'&gt;&lt;string&gt;colors&lt;/string&gt;&lt;/var&gt;&lt;/struct&gt;&lt;/data&gt;&lt;/wddxPacket&gt; + </programlisting></para> + + </refsect1> + </refentry> + + <refentry id="function.wddx-packet-start"> + <refnamediv> + <refname>wddx_packet_start</refname> + <refpurpose>Beginnt ein neue WDDX Packet mit einer 'Structure' darin</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>wddx_packet_start</function></funcdef> + <paramdef>string + <parameter><optional>kommentar</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <function>wddx_packet_start</function> wird verwendet um ein neues + WDDX Paket beginnen um die Variablen nachhinein zu ergänzen. + Ein optionaler <parameter>kommentar</parameter> String kann angegeben werden. + Es wird eine Packet ID zurückgegeben, die in später in Funktionen + verwendet werden kann. Desweiteren wird automatisch 'Structure' + Definition erzeugt um die Variablen aufnehmen zu können.</para> + + </refsect1> + </refentry> + + <refentry id="function.wddx-packet-end"> + <refnamediv> + <refname>wddx_packet_end</refname> + <refpurpose>Schliesst das WDDX Packet mit der angegebenen ID</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>wddx_packet_end</function></funcdef> + <paramdef>int <parameter>packet_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <function>wddx_packet_end</function> schliesst das WDDX Packet, + dass mit mit <parameter>packet_id</parameter> identifiziert wird + und gibt einen String mit dem Packet zurück.</para> + + </refsect1> + </refentry> + + <refentry id="function.wddx-add-vars"> + <refnamediv> + <refname>wddx_add_vars</refname> + <refpurpose>Fügt dem WDDX Packet mit der ID Werte hinzu</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef><function>wddx_add_vars</function></funcdef> + <paramdef>int <parameter>packet_id</parameter></paramdef> + <paramdef>mixed <parameter>name_var</parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <function>wddx_add_vars</function> wird verwendet um die übergebenen + Werte zu serialisiern und diese an das Packet anzuhängen, das mit + <parameter>packet_id</parameter> identifiziert wird. + Die Werteübergabe funktioniert genauso wie bei + <function>wddx_serialize_vars</function>.</para> + + </refsect1> + </refentry> + + <refentry id="function.wddx-deserialize"> + <refnamediv> + <refname>wddx_deserialize</refname> + <refpurpose>Deserialisiert ein WDDX Packet</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>wddx_deserialize</function></funcdef> + <paramdef>string <parameter>packet</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <function>wddx_deserialized</function> übernimmt einen + <parameter>packet</parameter> String and deserialisiert es. + Es wird entweder ein String, eine Nummer, oder Array als Ergebnis + zurückgegeben. 'Structures' werden in assoziative Arrays + deserialisiert.</para> + + </refsect1> + </refentry> + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/en/functions/printer.xml diff -u phpdoc/en/functions/printer.xml:1.5 phpdoc/en/functions/printer.xml:1.6 --- phpdoc/en/functions/printer.xml:1.5 Sat Jul 7 17:27:14 2001 +++ phpdoc/en/functions/printer.xml Sat Jul 7 19:11:22 2001 @@ -1,1681 +1,1681 @@ -<reference id="ref.printer"> - <title>Printer functions</title> - <titleabbrev>Printer</titleabbrev> - <partintro> - <simpara> - These functions are only available under Windows 9.x, ME, NT4 and - 2000. They have been added in PHP 4 (4.0.4). - </simpara> - </partintro> - - - <refentry id="function.printer-open"> - <refnamediv> - <refname>printer_open</refname> - <refpurpose>Open connection to a printer</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>printer_open</function></funcdef> - <paramdef>[string <parameter>devicename</parameter>]</paramdef> - </funcprototype> - </funcsynopsis> - <para> - This function tries to open a connection to the printer - <parameter>devicename</parameter>, and returns a handle on success - or &false; on failure. - </para> - <para> - If no parameter was given it tries to open a - connection to the default printer (if not specified in php.ini as - printer.default_printer, php tries to detect it). - </para> - <para> - <function>printer_open</function> also starts a device context. - </para> - <example> - <title><function>printer_open</function> example</title> - <programlisting role="php"> -$handle = printer_open("HP Deskjet 930c"); -$handle = printer_open(); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-abort"> - <refnamediv> - <refname>printer_abort</refname> - <refpurpose>Deletes the printer's spool file</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_abort</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - This function deletes the printers spool file. - </para> - <para> - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <example> - <title><function>printer_abort</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_abort($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-close"> - <refnamediv> - <refname>printer_close</refname> - <refpurpose>Close an open printer connection</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_close</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - This function closes the printer connection. - <function>printer_close</function> also closes the active device - context. - </para> - <para> - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <example> - <title><function>printer_close</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-write"> - <refnamediv> - <refname>printer_write</refname> - <refpurpose>Write data to the printer</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_write</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>string <parameter>content</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Writes <parameter>content</parameter> directly to the printer, and - returns &true; on success or &false; if it failed. - </para> - <para> - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <example> - <title><function>printer_write</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_write($handle, "Text to print"); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-list"> - <refnamediv> - <refname>printer_list</refname> - <refpurpose>Return an array of printers attached to the server - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>printer_list</function></funcdef> - <paramdef>int <parameter>enumtype</parameter></paramdef> - <paramdef>[string <parameter>name</parameter></paramdef> - <paramdef>[int <parameter>level</parameter>]]</paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function enumerates available printers and their capabilities. - <parameter>level</parameter> sets the level of information request. - Can be 1,2,4 or 5. <parameter>enumtype</parameter> must be one of the - following predefined constants: - <itemizedlist> - <listitem> - <simpara> - <parameter>PRINTER_ENUM_LOCAL</parameter>: - enumerates the locally installed printers. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_ENUM_NAME</parameter>: - enumerates the printer of <parameter>name</parameter>, can be a server, - domain or print provider. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_ENUM_SHARED</parameter>: - this parameter can't be used alone, it has to be OR'ed with other - parameters, i.e. PRINTER_ENUM_LOCAL to detect the locally shared - printers. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_ENUM_DEFAULT</parameter>: - (Win9.x only) enumerates the default printer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_ENUM_CONNECTIONS</parameter>: - (WinNT/2000 only) enumerates the printers to which the user has - made connections. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_ENUM_NETWORK</parameter>: - (WinNT/2000 only) enumerates network printers in the computer's - domain. Only valid if <parameter>level</parameter> is 1. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_ENUM_REMOTE</parameter>: - (WinNT/2000 only) enumerates network printers and print servers in the - computer's domain. Only valid if <parameter>level</parameter> is 1. - </simpara> - </listitem> - </itemizedlist> - </para> - <example> - <title><function>printer_list</function> example</title> - <programlisting role="php"> -/* detect locally shared printer */ -var_dump( printer_list(PRINTER_ENUM_LOCAL | PRINTER_ENUM_SHARED) ); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-set-option"> - <refnamediv> - <refname>printer_set_option</refname> - <refpurpose>Configure the printer connection</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_set_option</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>int <parameter>option</parameter></paramdef> - <paramdef>mixed <parameter>value</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function sets the following options for the current connection: - <parameter>handle</parameter> must be a valid handle to a printer. - For <parameter>option</parameter> can be one of the following constants: - <itemizedlist> - <listitem> - <simpara> - <parameter>PRINTER_COPIES</parameter>: - sets how many copies should be printed, <parameter>value</parameter> - must be an integer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_MODE</parameter>: - specifies the type of data (text, raw or emf), - <parameter>value</parameter> must be a string. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TITLE</parameter>: - specifies the name of the document, <parameter>value</parameter> - must be a string. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_ORIENTATION</parameter>: - specifies the orientation of the paper, <parameter>value</parameter> - can be either PRINTER_ORIENTATION_PORTRAIT or - PRINTER_ORIENTATION_LANDSCAPE - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_RESOLUTION_Y</parameter>: - specifies the y-resolution in DPI, <parameter>value</parameter> - must be an integer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_RESOLUTION_X</parameter>: - specifies the x-resolution in DPI, <parameter>value</parameter> - must be an integer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PAPER_FORMAT</parameter>: - specifies the a predefined paper format, set <parameter>value</parameter> - to PRINTER_FORMAT_CUSTOM if you want to specify a custom format with - PRINTER_PAPER_WIDTH and PRINTER_PAPER_LENGTH. <parameter>value</parameter> - can be one of the following constants. - </simpara> - <itemizedlist> - <listitem> - <simpara> - <parameter> PRINTER_FORMAT_CUSTOM</parameter>: - let's you specify a custom paper format. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter> PRINTER_FORMAT_LETTER</parameter>: - specifies standard letter format (8 1/2- by 11-inches). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter> PRINTER_FORMAT_LETTER</parameter>: - specifies standard legal format (8 1/2- by 14-inches). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FORMAT_A3</parameter>: - specifies standard A3 format (297- by 420-millimeters). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FORMAT_A4</parameter>: - specifies standard A4 format (210- by 297-millimeters). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FORMAT_A5</parameter>: - specifies standard A5 format (148- by 210-millimeters). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FORMAT_B4</parameter>: - specifies standard B4 format (250- by 354-millimeters). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FORMAT_B5</parameter>: - specifies standard B5 format (182- by 257-millimeter). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FORMAT_FOLIO</parameter>: - specifies standard FOLIO format (8 1/2- by 13-inch). - </simpara> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PAPER_LENGTH</parameter>: - if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, - PRINTER_PAPER_LENGTH specifies a custom paper length in mm, - <parameter>value</parameter> must be an integer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PAPER_WIDTH</parameter>: - if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, - PRINTER_PAPER_WIDTH specifies a custom paper width in mm, - <parameter>value</parameter> must be an integer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_SCALE</parameter>: - specifies the factor by which the printed output is to be scaled. - the page size is scaled from the physical page size by a factor - of scale/100. for example if you set the scale to 50, the output - would be half of it's original size. <parameter>value</parameter> - must be an integer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BACKGROUND_COLOR</parameter>: - specifies the background color for the actual device context, - <parameter>value</parameter> must be a string containing the rgb - information in hex format i.e. "005533". - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TEXT_COLOR</parameter>: - specifies the text color for the actual device context, - <parameter>value</parameter> must be a string containing the rgb - information in hex format i.e. "005533". - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TEXT_ALIGN</parameter>: - specifies the text alignment for the actual device context, - <parameter>value</parameter> can be combined through OR'ing the - following constants: - </simpara> - <itemizedlist> - <listitem> - <simpara> - <parameter>PRINTER_TA_BASELINE</parameter>: - text will be aligned at the base line. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TA_BOTTOM</parameter>: - text will be aligned at the bottom. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TA_TOP</parameter>: - text will be aligned at the top. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TA_CENTER</parameter>: - text will be aligned at the center. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TA_LEFT</parameter>: - text will be aligned at the left. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_TA_RIGHT</parameter>: - text will be aligned at the right. - </simpara> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </para> - <example> - <title><function>printer_set_option</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_set_option($handle, PRINTER_SCALE, 75); -printer_set_option($handle, PRINTER_TEXT_ALIGN, PRINTER_TA_LEFT); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-get-option"> - <refnamediv> - <refname>printer_get_option</refname> - <refpurpose>Retrieve printer configuration data</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>printer_get_option</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>string <parameter>option</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function retrieves the configuration setting of <parameter>option</parameter>. - <parameter>handle</parameter> must be a valid handle to a printer. - Take a look at <function>printer_set_option</function> for the settings that can - be retrieved, additionally the following settings can be retrieved: - <itemizedlist> - <listitem> - <simpara> - <parameter>PRINTER_DEVICENAME</parameter> - returns the devicename of the printer. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_DRIVERVERSION</parameter> - returns the printer driver version. - </simpara> - </listitem> - </itemizedlist> - </para> - <example> - <title><function>printer_get_option</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -print printer_get_option($handle, PRINTER_DRIVERVERSION); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-create-dc"> - <refnamediv> - <refname>printer_create_dc</refname> - <refpurpose>Create a new device context</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_create_dc</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function creates a new device context. A device context is used - to customize the graphic objects of the document. - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <example> - <title><function>printer_create_dc</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle); -printer_start_page($handle); - -printer_create_dc($handle); -/* do some stuff with the dc */ -printer_set_option($handle, PRINTER_TEXT_COLOR, "333333"); -printer_draw_text($handle, 1, 1, "text"); -printer_delete_dc($handle); - -/* create another dc */ -printer_create_dc($handle); -printer_set_option($handle, PRINTER_TEXT_COLOR, "000000"); -printer_draw_text($handle, 1, 1, "text"); -/* do some stuff with the dc */ - -printer_delete_dc($handle); - -printer_endpage($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-delete-dc"> - <refnamediv> - <refname>printer_delete_dc</refname> - <refpurpose>Delete a device context</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_delete_dc</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function deletes the device context and returns &true; on success, - or &false; if an error occurred. For an example see - <function>printer_create_dc</function>. <parameter>handle</parameter> - must be a valid handle to a printer. - </para> - </refsect1> - </refentry> - - - <refentry id="function.printer-start-doc"> - <refnamediv> - <refname>printer_start_doc</refname> - <refpurpose>Start a new document</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_start_doc</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>[string <parameter>document</parameter>]</paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function creates a new document in the printer spooler. A document - can contain multiple pages, it's used to schedule the print job in the - spooler. <parameter>handle</parameter> must be a valid handle to a - printer. The optional parameter <parameter>document</parameter> can be - used to set an alternative document name. - </para> - <example> - <title><function>printer_start_doc</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - - <refentry id="function.printer-end-doc"> - <refnamediv> - <refname>printer_end_doc</refname> - <refpurpose>Close document</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_end_doc</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function creates a new document in the printer spooler. A document - can contain multiple pages, it's used to schedule the print job in the - spooler. For an example see <function>printer_start_doc</function>. - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - </refsect1> - </refentry> - - - <refentry id="function.printer-start-page"> - <refnamediv> - <refname>printer_start_page</refname> - <refpurpose>Start a new page</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_start_page</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function creates a new page in the active document. For an - example see <function>printer_start_doc</function>. - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - </refsect1> - </refentry> - - - <refentry id="function.printer-end-page"> - <refnamediv> - <refname>printer_end_page</refname> - <refpurpose>Close active page</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_end_page</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function closes the active page in the active document. For an - example see <function>printer_start_doc</function>. - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - </refsect1> - </refentry> - - - <refentry id="function.printer-create-pen"> - <refnamediv> - <refname>printer_create_pen</refname> - <refpurpose>Create a new pen</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>printer_create_pen</function> - </funcdef> - <paramdef>int <parameter>style</parameter></paramdef> - <paramdef>int <parameter>width</parameter></paramdef> - <paramdef>string <parameter>color</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function creates a new pen and returns a handle to it. A pen is - used to draw lines and curves. For an example see - <function>printer_select_pen</function>. <parameter>color</parameter> - must be a color in RGB hex format, i.e. "000000" for black, - <parameter>width</parameter> specifies the width of the pen whereas - <parameter>style</parameter> must be one of the following constants: - <itemizedlist> - <listitem> - <simpara> - <parameter>PRINTER_PEN_SOLID</parameter>: - creates a solid pen. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PEN_DASH</parameter>: - creates a dashed pen. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PEN_DOT</parameter>: - creates a dotted pen. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PEN_DASHDOT</parameter>: - creates a pen with dashes and dots. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PEN_DASHDOTDOT</parameter>: - creates a pen with dashes and double dots. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_PEN_INVISIBLE</parameter>: - creates an invisible pen. - </simpara> - </listitem> - </itemizedlist> - </para> - </refsect1> - </refentry> - - - <refentry id="function.printer-delete-pen"> - <refnamediv> - <refname>printer_delete_pen</refname> - <refpurpose>Delete a pen</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_delete_pen</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function deletes the selected pen. For an example see - <function>printer_select_pen</function>. It returns &true; on success, - or &false; otherwise. <parameter>handle</parameter> must be a valid - handle to a pen. - </para> - </refsect1> - </refentry> - - - <refentry id="function.printer-select-pen"> - <refnamediv> - <refname>printer_select_pen</refname> - <refpurpose>Select a pen</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_select_pen</function> - </funcdef> - <paramdef>resource <parameter>printer_handle</parameter></paramdef> - <paramdef>resource <parameter>pen_handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function selects a pen as the active drawing object of the actual - device context. A pen is used to draw lines and curves. I.e. if you draw - a single line the pen is used. If you draw an rectangle the pen is used - to draw the borders, while the brush is used to fill the shape. - If you haven't selected a pen before drawing shapes, the shape won't be - outlined. <parameter>printer_handle</parameter> must be a valid handle - to a printer. <parameter>pen_handle</parameter> must be a valid handle - to a pen. - </para> - <example> - <title> - <function>printer_select_pen</function> example - </title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, "2222FF"); -printer_select_pen($handle, $pen); - -printer_draw_line($handle, 1, 60, 500, 60); - -printer_delete_pen($pen); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-create-brush"> - <refnamediv> - <refname>printer_create_brush</refname> - <refpurpose>Create a new brush</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>printer_create_brush</function> - </funcdef> - <paramdef>int <parameter>style</parameter></paramdef> - <paramdef>string <parameter>color</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function creates a new brush and returns a handle to it. A brush - is used to fill shapes. For an example see - <function>printer_select_brush</function>. <parameter>color</parameter> - must be a color in RGB hex format, i.e. "000000" for black, - <parameter>style</parameter> must be one of the following constants: - <itemizedlist> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_SOLID</parameter>: - creates a brush with a solid color. - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_DIAGONAL</parameter>: - creates a brush with a 45-degree upward left-to-right hatch ( / ). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_CROSS</parameter>: - creates a brush with a cross hatch ( + ). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_DIAGCROSS</parameter>: - creates a brush with a 45 cross hatch ( x ). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_FDIAGONAL</parameter>: - creates a brush with a 45-degree downward left-to-right hatch ( \ ). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_HORIZONTAL</parameter>: - creates a brush with a horizontal hatch ( - ). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_VERTICAL</parameter>: - creates a brush with a vertical hatch ( | ). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_BRUSH_CUSTOM</parameter>: - creates a custom brush from an BMP file. The second parameter - is used to specify the BMP instead of the RGB color code. - </simpara> - </listitem> - </itemizedlist> - </para> - </refsect1> - </refentry> - - <refentry id="function.printer-delete-brush"> - <refnamediv> - <refname>printer_delete_brush</refname> - <refpurpose>Delete a brush</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_delete_brush</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function deletes the selected brush. For an example see - <function>printer_select_brush</function>. It returns &true; on - success, or &false; otherwise. <parameter>handle</parameter> - must be a valid handle to a brush. - </para> - </refsect1> - </refentry> - - <refentry id="function.printer-select-brush"> - <refnamediv> - <refname>printer_select_brush</refname> - <refpurpose>Select a brush</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_select_brush</function> - </funcdef> - <paramdef>resource <parameter>printer_handle</parameter></paramdef> - <paramdef>resource <parameter>brush_handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function selects a brush as the active drawing object of the actual - device context. A brush is used to fill shapes. If you draw an rectangle - the brush is used to draw the shapes, while the pen is used to draw the - border. - If you haven't selected a brush before drawing shapes, the shape won't - be filled. <parameter>printer_handle</parameter> must be a valid handle - to a printer. <parameter>brush_handle</parameter> must be a valid handle - to a brush. - </para> - <example> - <title> - <function>printer_select_brush</function> example - </title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); -printer_select_pen($handle, $pen); -$brush = printer_create_brush(PRINTER_BRUSH_CUSTOM, "c:\\brush.bmp"); -printer_select_brush($handle, $brush); - -printer_draw_rectangle($handle, 1,1,500,500); - -printer_delete_brush($brush); - -$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "000000"); -printer_select_brush($handle, $brush); -printer_draw_rectangle($handle, 1,501,500,1001); -printer_delete_brush($brush); - -printer_delete_pen($pen); - - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-create-font"> - <refnamediv> - <refname>printer_create_font</refname> - <refpurpose>Create a new font</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>printer_create_font</function> - </funcdef> - <paramdef>string <parameter>face</parameter></paramdef> - <paramdef>int <parameter>height</parameter></paramdef> - <paramdef>int <parameter>width</parameter></paramdef> - <paramdef>int <parameter>font_weight</parameter></paramdef> - <paramdef>bool <parameter>italic</parameter></paramdef> - <paramdef>bool <parameter>underline</parameter></paramdef> - <paramdef>bool <parameter>strikeout</parameter></paramdef> - <paramdef>int <parameter>orientaton</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function creates a new font and returns a handle to it. A font is - used to draw text. For an example see - <function>printer_select_font</function>. <parameter>face</parameter> - must be a string specifying the font face. <parameter>height</parameter> - specifies the font height, and <parameter>width</parameter> the font - width. The <parameter>font_weight</parameter> specifies the font weight - (400 is normal), and can be one of the following predefined constants. - <itemizedlist> - <listitem> - <simpara> - <parameter>PRINTER_FW_THIN</parameter>: - sets the font weight to thin (100). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FW_ULTRALIGHT</parameter>: - sets the font weight to ultra light (200). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FW_LIGHT</parameter>: - sets the font weight to light (300). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FW_NORMAL</parameter>: - sets the font weight to normal (400). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FW_MEDIUM</parameter>: - sets the font weight to medium (500). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FW_BOLD</parameter>: - sets the font weight to bold (700). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FW_ULTRABOLD</parameter>: - sets the font weight to ultra bold (800). - </simpara> - </listitem> - <listitem> - <simpara> - <parameter>PRINTER_FW_HEAVY</parameter>: - sets the font weight to heavy (900). - </simpara> - </listitem> - </itemizedlist> - <parameter>italic</parameter> can be &true; or &false;, and sets whether the font should be italic. - <parameter>underline</parameter> can be &true; or &false;, and sets whether the font should be underlined. - <parameter>strikeout</parameter> can be &true; or &false;, and sets whether the font should be striked out. - <parameter>orientation</parameter> specifies a rotation. - For an example see <function>printer_select_font</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.printer-delete-font"> - <refnamediv> - <refname>printer_delete_font</refname> - <refpurpose>Delete a font</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>printer_delete_font</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function deletes the selected font. For an example see - <function>printer_select_font</function>. It returns &true; on success, - or &false; otherwise. <parameter>handle</parameter> must be a valid - handle to a font. - </para> - </refsect1> - </refentry> - - <refentry id="function.printer-select-font"> - <refnamediv> - <refname>printer_select_font</refname> - <refpurpose>Select a font</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_select_font</function> - </funcdef> - <paramdef>resource <parameter>printer_handle</parameter></paramdef> - <paramdef>resource <parameter>font_handle</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function selects a font to draw text. - <parameter>printer_handle</parameter> must be a valid handle to a - printer. <parameter>font_handle</parameter> must be a valid handle - to a font. - </para> - <example> - <title> - <function>printer_select_font</function> example - </title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$font = printer_create_font("Arial", 148, 76, PRINTER_FW_MEDIUM, false, false, false, -50); -printer_select_font($handle, $font); -printer_draw_text($handle, "PHP is simply cool", 40, 40); -printer_delete_font($font); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-logical-fontheight"> - <refnamediv> - <refname>printer_logical_fontheight</refname> - <refpurpose>Get logical font height</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>printer_logical_fontheight</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>int <parameter>height</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function calculates the logical font height of - <parameter>height</parameter>. <parameter>handle</parameter> must - be a valid handle to a printer. - </para> - <example> - <title> - <function>printer_logical_fontheight</function> example - </title> - <programlisting role="php"> -$handle = printer_open(); -print printer_logical_fontheight($handle, 72); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-roundrect"> - <refnamediv> - <refname>printer_draw_roundrect</refname> - <refpurpose>Draw a rectangle with rounded corners</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_roundrect</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>int <parameter>ul_x</parameter></paramdef> - <paramdef>int <parameter>ul_y</parameter></paramdef> - <paramdef>int <parameter>lr_x</parameter></paramdef> - <paramdef>int <parameter>lr_y</parameter></paramdef> - <paramdef>int <parameter>width</parameter></paramdef> - <paramdef>int <parameter>height</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws a rectangle with rounded corners. - </para> - <para> - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <para> - <parameter>ul_x</parameter> is the upper left x coordinate of the rectangle. - </para> - <para> - <parameter>ul_y</parameter> is the upper left y coordinate of the rectangle. - </para> - <para> - <parameter>lr_x</parameter> is the lower right x coordinate of the rectangle. - </para> - <para> - <parameter>lr_y</parameter> is the lower right y coordinate of the rectangle. - </para> - <para> - <parameter>width</parameter> is the width of the ellipse. - </para> - <para> - <parameter>height</parameter> is the height of the ellipse. - </para> - <example> - <title> - <function>printer_draw_roundrect</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); -printer_select_pen($handle, $pen); - -$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); -printer_select_brush($handle, $brush); - -printer_draw_roundrect($handle, 1, 1, 500, 500, 200, 200); - -printer_delete_brush($brush); -printer_delete_pen($pen); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-rectangle"> - <refnamediv> - <refname>printer_draw_rectangle</refname> - <refpurpose>Draw a rectangle</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_rectangle</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>int <parameter>ul_x</parameter></paramdef> - <paramdef>int <parameter>ul_y</parameter></paramdef> - <paramdef>int <parameter>lr_x</parameter></paramdef> - <paramdef>int <parameter>lr_y</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws a rectangle. - </para> - <para> - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <para> - <parameter>ul_x</parameter> is the upper left x coordinate of the rectangle. - </para> - <para> - <parameter>ul_y</parameter> is the upper left y coordinate of the rectangle. - </para> - <para> - <parameter>lr_x</parameter> is the lower right x coordinate of the rectangle. - </para> - <para> - <parameter>lr_y</parameter> is the lower right y coordinate of the rectangle. - </para> - <example> - <title> - <function>printer_draw_rectangle</function> example - </title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); -printer_select_pen($handle, $pen); - -$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); -printer_select_brush($handle, $brush); - -printer_draw_rectangle($handle, 1, 1, 500, 500); - -printer_delete_brush($brush); -printer_delete_pen($pen); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-elipse"> - <refnamediv> - <refname>printer_draw_elipse</refname> - <refpurpose>Draw an ellipse</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_elipse</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>int <parameter>ul_x</parameter></paramdef> - <paramdef>int <parameter>ul_y</parameter></paramdef> - <paramdef>int <parameter>lr_x</parameter></paramdef> - <paramdef>int <parameter>lr_y</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws an ellipse. - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <para> - <parameter>ul_x</parameter> is the upper left x coordinate of the ellipse. - </para> - <para> - <parameter>ul_y</parameter> is the upper left y coordinate of the ellipse. - </para> - <para> - <parameter>lr_x</parameter> is the lower right x coordinate of the ellipse. - </para> - <para> - <parameter>lr_y</parameter> is the lower right y coordinate of the ellipse. - </para> - <example> - <title> - <function>printer_draw_elipse</function> example - </title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); -printer_select_pen($handle, $pen); - -$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); -printer_select_brush($handle, $brush); - -printer_draw_elipse($handle, 1, 1, 500, 500); - -printer_delete_brush($brush); -printer_delete_pen($pen); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-text"> - <refnamediv> - <refname>printer_draw_text</refname> - <refpurpose>Draw text</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_text</function> - </funcdef> - <paramdef>resource <parameter>printer_handle</parameter></paramdef> - <paramdef>string <parameter>text</parameter></paramdef> - <paramdef>int <parameter>x</parameter></paramdef> - <paramdef>int <parameter>y</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws <parameter>text</parameter> at position - <parameter>x</parameter>, <parameter>y</parameter> using the selected - font. <parameter>printer_handle</parameter> must be a valid handle to - a printer. - </para> - <example> - <title><function>printer_draw_text</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$font = printer_create_font("Arial",72,48,400,false,false,false,0); -printer_select_font($handle, $font); -printer_draw_text($handle, "test", 10, 10); -printer_delete_font($font); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-line"> - <refnamediv> - <refname>printer_draw_line</refname> - <refpurpose>Draw a line</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_line</function></funcdef> - <paramdef>resource <parameter>printer_handle</parameter></paramdef> - <paramdef>int <parameter>from_x</parameter></paramdef> - <paramdef>int <parameter>from_y</parameter></paramdef> - <paramdef>int <parameter>to_x</parameter></paramdef> - <paramdef>int <parameter>to_y</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws a line from position - <parameter>from_x</parameter>, <parameter>from_y</parameter> to - position <parameter>to_x</parameter>, <parameter>to_y</parameter> - using the selected pen. <parameter>printer_handle</parameter> must - be a valid handle to a printer. - </para> - <example> - <title><function>printer_draw_line</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, 000000"); -printer_select_pen($handle, $pen); - -printer_draw_line($handle, 1, 10, 1000, 10); -printer_draw_line($handle, 1, 60, 500, 60); - -printer_delete_pen($pen); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-chord"> - <refnamediv> - <refname>printer_draw_chord</refname> - <refpurpose>Draw a chord</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_chord</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>int <parameter>rec_x</parameter></paramdef> - <paramdef>int <parameter>rec_y</parameter></paramdef> - <paramdef>int <parameter>rec_x1</parameter></paramdef> - <paramdef>int <parameter>rec_y1</parameter></paramdef> - <paramdef>int <parameter>rad_x</parameter></paramdef> - <paramdef>int <parameter>rad_y</parameter></paramdef> - <paramdef>int <parameter>rad_x1</parameter></paramdef> - <paramdef>int <parameter>rad_y1</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws an chord. - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <para> - <parameter>rec_x</parameter> is the upper left x coordinate of the - bounding rectangle. - </para> - <para> - <parameter>rec_y</parameter> is the upper left y coordinate of the - bounding rectangle. - </para> - <para> - <parameter>rec_x1</parameter> is the lower right x coordinate of the - bounding rectangle. - </para> - <para> - <parameter>rec_y1</parameter> is the lower right y coordinate of - the bounding rectangle. - </para> - <para> - <parameter>rad_x</parameter> is x coordinate of the radial defining - the beginning of the chord. - </para> - <para> - <parameter>rad_y</parameter> is y coordinate of the radial defining - the beginning of the chord. - </para> - <para> - <parameter>rad_x1</parameter> is x coordinate of the radial defining - the end of the chord. - </para> - <para> - <parameter>rad_y1</parameter> is y coordinate of the radial defining - the end of the chord. - </para> - <example> - <title><function>printer_draw_chord</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); -printer_select_pen($handle, $pen); - -$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); -printer_select_brush($handle, $brush); - -printer_draw_chord($handle, 1, 1, 500, 500, 1, 1, 500, 1); - -printer_delete_brush($brush); -printer_delete_pen($pen); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-pie"> - <refnamediv> - <refname>printer_draw_pie</refname> - <refpurpose>Draw a pie</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_pie</function></funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>int <parameter>rec_x</parameter></paramdef> - <paramdef>int <parameter>rec_y</parameter></paramdef> - <paramdef>int <parameter>rec_x1</parameter></paramdef> - <paramdef>int <parameter>rec_y1</parameter></paramdef> - <paramdef>int <parameter>rad1_x</parameter></paramdef> - <paramdef>int <parameter>rad1_y</parameter></paramdef> - <paramdef>int <parameter>rad2_x</parameter></paramdef> - <paramdef>int <parameter>rad2_y</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws an pie. - <parameter>handle</parameter> must be a valid handle to a printer. - </para> - <para> - <parameter>rec_x</parameter> is the upper left x coordinate of - the bounding rectangle. - </para> - <para> - <parameter>rec_y</parameter> is the upper left y coordinate of - the bounding rectangle. - </para> - <para> - <parameter>rec_x1</parameter> is the lower right x coordinate of - the bounding rectangle. - </para> - <para> - <parameter>rec_y1</parameter> is the lower right y coordinate of - the bounding rectangle. - </para> - <para> - <parameter>rad1_x</parameter> is x coordinate of the first - radial's ending. - </para> - <para> - <parameter>rad1_y</parameter> is y coordinate of the first - radial's ending. - </para> - <para> - <parameter>rad2_x</parameter> is x coordinate of the second - radial's ending. - </para> - <para> - <parameter>rad2_y</parameter> is y coordinate of the second - radial's ending. - </para> - <example> - <title><function>printer_draw_chord</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); -printer_select_pen($handle, $pen); - -$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); -printer_select_brush($handle, $brush); - -printer_draw_pie($handle, 1, 1, 500, 500, 1, 1, 500, 1); - -printer_delete_brush($brush); -printer_delete_pen($pen); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.printer-draw-bmp"> - <refnamediv> - <refname>printer_draw_bmp</refname> - <refpurpose>Draw a bmp</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>printer_draw_bmp</function> - </funcdef> - <paramdef>resource <parameter>handle</parameter></paramdef> - <paramdef>string <parameter>filename</parameter></paramdef> - <paramdef>int <parameter>x</parameter></paramdef> - <paramdef>int <parameter>y</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - The function simply draws an bmp the bitmap - <parameter>filename</parameter> at position <parameter>x</parameter>, - <parameter>y</parameter>. <parameter>handle</parameter> must be a - valid handle to a printer. - </para> - <para> - The function returns &true; on success, or otherwise &false;. - </para> - <example> - <title><function>printer_draw_bmp</function> example</title> - <programlisting role="php"> -$handle = printer_open(); -printer_start_doc($handle, "My Document"); -printer_start_page($handle); - -printer_draw_bmp($handle, "c:\\image.bmp", 1, 1); - -printer_end_page($handle); -printer_end_doc($handle); -printer_close($handle); - </programlisting> - </example> - </refsect1> - </refentry> -</reference> -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> +<reference id="ref.printer"> + <title>Printer functions</title> + <titleabbrev>Printer</titleabbrev> + <partintro> + <simpara> + These functions are only available under Windows 9.x, ME, NT4 and + 2000. They have been added in PHP 4 (4.0.4). + </simpara> + </partintro> + + + <refentry id="function.printer-open"> + <refnamediv> + <refname>printer_open</refname> + <refpurpose>Open connection to a printer</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>printer_open</function></funcdef> + <paramdef>[string <parameter>devicename</parameter>]</paramdef> + </funcprototype> + </funcsynopsis> + <para> + This function tries to open a connection to the printer + <parameter>devicename</parameter>, and returns a handle on success + or &false; on failure. + </para> + <para> + If no parameter was given it tries to open a + connection to the default printer (if not specified in php.ini as + printer.default_printer, php tries to detect it). + </para> + <para> + <function>printer_open</function> also starts a device context. + </para> + <example> + <title><function>printer_open</function> example</title> + <programlisting role="php"> +$handle = printer_open("HP Deskjet 930c"); +$handle = printer_open(); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-abort"> + <refnamediv> + <refname>printer_abort</refname> + <refpurpose>Deletes the printer's spool file</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_abort</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + This function deletes the printers spool file. + </para> + <para> + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <example> + <title><function>printer_abort</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_abort($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-close"> + <refnamediv> + <refname>printer_close</refname> + <refpurpose>Close an open printer connection</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_close</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + This function closes the printer connection. + <function>printer_close</function> also closes the active device + context. + </para> + <para> + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <example> + <title><function>printer_close</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-write"> + <refnamediv> + <refname>printer_write</refname> + <refpurpose>Write data to the printer</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_write</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>string <parameter>content</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Writes <parameter>content</parameter> directly to the printer, and + returns &true; on success or &false; if it failed. + </para> + <para> + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <example> + <title><function>printer_write</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_write($handle, "Text to print"); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-list"> + <refnamediv> + <refname>printer_list</refname> + <refpurpose>Return an array of printers attached to the server + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>printer_list</function></funcdef> + <paramdef>int <parameter>enumtype</parameter></paramdef> + <paramdef>[string <parameter>name</parameter></paramdef> + <paramdef>[int <parameter>level</parameter>]]</paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function enumerates available printers and their capabilities. + <parameter>level</parameter> sets the level of information request. + Can be 1,2,4 or 5. <parameter>enumtype</parameter> must be one of the + following predefined constants: + <itemizedlist> + <listitem> + <simpara> + <parameter>PRINTER_ENUM_LOCAL</parameter>: + enumerates the locally installed printers. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_ENUM_NAME</parameter>: + enumerates the printer of <parameter>name</parameter>, can be a server, + domain or print provider. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_ENUM_SHARED</parameter>: + this parameter can't be used alone, it has to be OR'ed with other + parameters, i.e. PRINTER_ENUM_LOCAL to detect the locally shared + printers. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_ENUM_DEFAULT</parameter>: + (Win9.x only) enumerates the default printer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_ENUM_CONNECTIONS</parameter>: + (WinNT/2000 only) enumerates the printers to which the user has + made connections. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_ENUM_NETWORK</parameter>: + (WinNT/2000 only) enumerates network printers in the computer's + domain. Only valid if <parameter>level</parameter> is 1. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_ENUM_REMOTE</parameter>: + (WinNT/2000 only) enumerates network printers and print servers in the + computer's domain. Only valid if <parameter>level</parameter> is 1. + </simpara> + </listitem> + </itemizedlist> + </para> + <example> + <title><function>printer_list</function> example</title> + <programlisting role="php"> +/* detect locally shared printer */ +var_dump( printer_list(PRINTER_ENUM_LOCAL | PRINTER_ENUM_SHARED) ); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-set-option"> + <refnamediv> + <refname>printer_set_option</refname> + <refpurpose>Configure the printer connection</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_set_option</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>int <parameter>option</parameter></paramdef> + <paramdef>mixed <parameter>value</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function sets the following options for the current connection: + <parameter>handle</parameter> must be a valid handle to a printer. + For <parameter>option</parameter> can be one of the following constants: + <itemizedlist> + <listitem> + <simpara> + <parameter>PRINTER_COPIES</parameter>: + sets how many copies should be printed, <parameter>value</parameter> + must be an integer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_MODE</parameter>: + specifies the type of data (text, raw or emf), + <parameter>value</parameter> must be a string. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TITLE</parameter>: + specifies the name of the document, <parameter>value</parameter> + must be a string. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_ORIENTATION</parameter>: + specifies the orientation of the paper, <parameter>value</parameter> + can be either PRINTER_ORIENTATION_PORTRAIT or + PRINTER_ORIENTATION_LANDSCAPE + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_RESOLUTION_Y</parameter>: + specifies the y-resolution in DPI, <parameter>value</parameter> + must be an integer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_RESOLUTION_X</parameter>: + specifies the x-resolution in DPI, <parameter>value</parameter> + must be an integer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PAPER_FORMAT</parameter>: + specifies the a predefined paper format, set <parameter>value</parameter> + to PRINTER_FORMAT_CUSTOM if you want to specify a custom format with + PRINTER_PAPER_WIDTH and PRINTER_PAPER_LENGTH. <parameter>value</parameter> + can be one of the following constants. + </simpara> + <itemizedlist> + <listitem> + <simpara> + <parameter> PRINTER_FORMAT_CUSTOM</parameter>: + let's you specify a custom paper format. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter> PRINTER_FORMAT_LETTER</parameter>: + specifies standard letter format (8 1/2- by 11-inches). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter> PRINTER_FORMAT_LETTER</parameter>: + specifies standard legal format (8 1/2- by 14-inches). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FORMAT_A3</parameter>: + specifies standard A3 format (297- by 420-millimeters). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FORMAT_A4</parameter>: + specifies standard A4 format (210- by 297-millimeters). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FORMAT_A5</parameter>: + specifies standard A5 format (148- by 210-millimeters). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FORMAT_B4</parameter>: + specifies standard B4 format (250- by 354-millimeters). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FORMAT_B5</parameter>: + specifies standard B5 format (182- by 257-millimeter). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FORMAT_FOLIO</parameter>: + specifies standard FOLIO format (8 1/2- by 13-inch). + </simpara> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PAPER_LENGTH</parameter>: + if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, + PRINTER_PAPER_LENGTH specifies a custom paper length in mm, + <parameter>value</parameter> must be an integer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PAPER_WIDTH</parameter>: + if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, + PRINTER_PAPER_WIDTH specifies a custom paper width in mm, + <parameter>value</parameter> must be an integer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_SCALE</parameter>: + specifies the factor by which the printed output is to be scaled. + the page size is scaled from the physical page size by a factor + of scale/100. for example if you set the scale to 50, the output + would be half of it's original size. <parameter>value</parameter> + must be an integer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BACKGROUND_COLOR</parameter>: + specifies the background color for the actual device context, + <parameter>value</parameter> must be a string containing the rgb + information in hex format i.e. "005533". + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TEXT_COLOR</parameter>: + specifies the text color for the actual device context, + <parameter>value</parameter> must be a string containing the rgb + information in hex format i.e. "005533". + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TEXT_ALIGN</parameter>: + specifies the text alignment for the actual device context, + <parameter>value</parameter> can be combined through OR'ing the + following constants: + </simpara> + <itemizedlist> + <listitem> + <simpara> + <parameter>PRINTER_TA_BASELINE</parameter>: + text will be aligned at the base line. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TA_BOTTOM</parameter>: + text will be aligned at the bottom. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TA_TOP</parameter>: + text will be aligned at the top. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TA_CENTER</parameter>: + text will be aligned at the center. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TA_LEFT</parameter>: + text will be aligned at the left. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_TA_RIGHT</parameter>: + text will be aligned at the right. + </simpara> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </para> + <example> + <title><function>printer_set_option</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_set_option($handle, PRINTER_SCALE, 75); +printer_set_option($handle, PRINTER_TEXT_ALIGN, PRINTER_TA_LEFT); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-get-option"> + <refnamediv> + <refname>printer_get_option</refname> + <refpurpose>Retrieve printer configuration data</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>printer_get_option</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>string <parameter>option</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function retrieves the configuration setting of <parameter>option</parameter>. + <parameter>handle</parameter> must be a valid handle to a printer. + Take a look at <function>printer_set_option</function> for the settings that can + be retrieved, additionally the following settings can be retrieved: + <itemizedlist> + <listitem> + <simpara> + <parameter>PRINTER_DEVICENAME</parameter> + returns the devicename of the printer. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_DRIVERVERSION</parameter> + returns the printer driver version. + </simpara> + </listitem> + </itemizedlist> + </para> + <example> + <title><function>printer_get_option</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +print printer_get_option($handle, PRINTER_DRIVERVERSION); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-create-dc"> + <refnamediv> + <refname>printer_create_dc</refname> + <refpurpose>Create a new device context</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_create_dc</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function creates a new device context. A device context is used + to customize the graphic objects of the document. + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <example> + <title><function>printer_create_dc</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle); +printer_start_page($handle); + +printer_create_dc($handle); +/* do some stuff with the dc */ +printer_set_option($handle, PRINTER_TEXT_COLOR, "333333"); +printer_draw_text($handle, 1, 1, "text"); +printer_delete_dc($handle); + +/* create another dc */ +printer_create_dc($handle); +printer_set_option($handle, PRINTER_TEXT_COLOR, "000000"); +printer_draw_text($handle, 1, 1, "text"); +/* do some stuff with the dc */ + +printer_delete_dc($handle); + +printer_endpage($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-delete-dc"> + <refnamediv> + <refname>printer_delete_dc</refname> + <refpurpose>Delete a device context</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_delete_dc</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function deletes the device context and returns &true; on success, + or &false; if an error occurred. For an example see + <function>printer_create_dc</function>. <parameter>handle</parameter> + must be a valid handle to a printer. + </para> + </refsect1> + </refentry> + + + <refentry id="function.printer-start-doc"> + <refnamediv> + <refname>printer_start_doc</refname> + <refpurpose>Start a new document</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_start_doc</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>[string <parameter>document</parameter>]</paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function creates a new document in the printer spooler. A document + can contain multiple pages, it's used to schedule the print job in the + spooler. <parameter>handle</parameter> must be a valid handle to a + printer. The optional parameter <parameter>document</parameter> can be + used to set an alternative document name. + </para> + <example> + <title><function>printer_start_doc</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + + <refentry id="function.printer-end-doc"> + <refnamediv> + <refname>printer_end_doc</refname> + <refpurpose>Close document</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_end_doc</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function creates a new document in the printer spooler. A document + can contain multiple pages, it's used to schedule the print job in the + spooler. For an example see <function>printer_start_doc</function>. + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + </refsect1> + </refentry> + + + <refentry id="function.printer-start-page"> + <refnamediv> + <refname>printer_start_page</refname> + <refpurpose>Start a new page</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_start_page</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function creates a new page in the active document. For an + example see <function>printer_start_doc</function>. + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + </refsect1> + </refentry> + + + <refentry id="function.printer-end-page"> + <refnamediv> + <refname>printer_end_page</refname> + <refpurpose>Close active page</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_end_page</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function closes the active page in the active document. For an + example see <function>printer_start_doc</function>. + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + </refsect1> + </refentry> + + + <refentry id="function.printer-create-pen"> + <refnamediv> + <refname>printer_create_pen</refname> + <refpurpose>Create a new pen</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>printer_create_pen</function> + </funcdef> + <paramdef>int <parameter>style</parameter></paramdef> + <paramdef>int <parameter>width</parameter></paramdef> + <paramdef>string <parameter>color</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function creates a new pen and returns a handle to it. A pen is + used to draw lines and curves. For an example see + <function>printer_select_pen</function>. <parameter>color</parameter> + must be a color in RGB hex format, i.e. "000000" for black, + <parameter>width</parameter> specifies the width of the pen whereas + <parameter>style</parameter> must be one of the following constants: + <itemizedlist> + <listitem> + <simpara> + <parameter>PRINTER_PEN_SOLID</parameter>: + creates a solid pen. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PEN_DASH</parameter>: + creates a dashed pen. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PEN_DOT</parameter>: + creates a dotted pen. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PEN_DASHDOT</parameter>: + creates a pen with dashes and dots. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PEN_DASHDOTDOT</parameter>: + creates a pen with dashes and double dots. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_PEN_INVISIBLE</parameter>: + creates an invisible pen. + </simpara> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + + <refentry id="function.printer-delete-pen"> + <refnamediv> + <refname>printer_delete_pen</refname> + <refpurpose>Delete a pen</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_delete_pen</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function deletes the selected pen. For an example see + <function>printer_select_pen</function>. It returns &true; on success, + or &false; otherwise. <parameter>handle</parameter> must be a valid + handle to a pen. + </para> + </refsect1> + </refentry> + + + <refentry id="function.printer-select-pen"> + <refnamediv> + <refname>printer_select_pen</refname> + <refpurpose>Select a pen</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_select_pen</function> + </funcdef> + <paramdef>resource <parameter>printer_handle</parameter></paramdef> + <paramdef>resource <parameter>pen_handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function selects a pen as the active drawing object of the actual + device context. A pen is used to draw lines and curves. I.e. if you draw + a single line the pen is used. If you draw an rectangle the pen is used + to draw the borders, while the brush is used to fill the shape. + If you haven't selected a pen before drawing shapes, the shape won't be + outlined. <parameter>printer_handle</parameter> must be a valid handle + to a printer. <parameter>pen_handle</parameter> must be a valid handle + to a pen. + </para> + <example> + <title> + <function>printer_select_pen</function> example + </title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, "2222FF"); +printer_select_pen($handle, $pen); + +printer_draw_line($handle, 1, 60, 500, 60); + +printer_delete_pen($pen); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-create-brush"> + <refnamediv> + <refname>printer_create_brush</refname> + <refpurpose>Create a new brush</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>printer_create_brush</function> + </funcdef> + <paramdef>int <parameter>style</parameter></paramdef> + <paramdef>string <parameter>color</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function creates a new brush and returns a handle to it. A brush + is used to fill shapes. For an example see + <function>printer_select_brush</function>. <parameter>color</parameter> + must be a color in RGB hex format, i.e. "000000" for black, + <parameter>style</parameter> must be one of the following constants: + <itemizedlist> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_SOLID</parameter>: + creates a brush with a solid color. + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_DIAGONAL</parameter>: + creates a brush with a 45-degree upward left-to-right hatch ( / ). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_CROSS</parameter>: + creates a brush with a cross hatch ( + ). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_DIAGCROSS</parameter>: + creates a brush with a 45 cross hatch ( x ). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_FDIAGONAL</parameter>: + creates a brush with a 45-degree downward left-to-right hatch ( \ ). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_HORIZONTAL</parameter>: + creates a brush with a horizontal hatch ( - ). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_VERTICAL</parameter>: + creates a brush with a vertical hatch ( | ). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_BRUSH_CUSTOM</parameter>: + creates a custom brush from an BMP file. The second parameter + is used to specify the BMP instead of the RGB color code. + </simpara> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="function.printer-delete-brush"> + <refnamediv> + <refname>printer_delete_brush</refname> + <refpurpose>Delete a brush</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_delete_brush</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function deletes the selected brush. For an example see + <function>printer_select_brush</function>. It returns &true; on + success, or &false; otherwise. <parameter>handle</parameter> + must be a valid handle to a brush. + </para> + </refsect1> + </refentry> + + <refentry id="function.printer-select-brush"> + <refnamediv> + <refname>printer_select_brush</refname> + <refpurpose>Select a brush</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_select_brush</function> + </funcdef> + <paramdef>resource <parameter>printer_handle</parameter></paramdef> + <paramdef>resource <parameter>brush_handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function selects a brush as the active drawing object of the actual + device context. A brush is used to fill shapes. If you draw an rectangle + the brush is used to draw the shapes, while the pen is used to draw the + border. + If you haven't selected a brush before drawing shapes, the shape won't + be filled. <parameter>printer_handle</parameter> must be a valid handle + to a printer. <parameter>brush_handle</parameter> must be a valid handle + to a brush. + </para> + <example> + <title> + <function>printer_select_brush</function> example + </title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); +printer_select_pen($handle, $pen); +$brush = printer_create_brush(PRINTER_BRUSH_CUSTOM, "c:\\brush.bmp"); +printer_select_brush($handle, $brush); + +printer_draw_rectangle($handle, 1,1,500,500); + +printer_delete_brush($brush); + +$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "000000"); +printer_select_brush($handle, $brush); +printer_draw_rectangle($handle, 1,501,500,1001); +printer_delete_brush($brush); + +printer_delete_pen($pen); + + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-create-font"> + <refnamediv> + <refname>printer_create_font</refname> + <refpurpose>Create a new font</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>printer_create_font</function> + </funcdef> + <paramdef>string <parameter>face</parameter></paramdef> + <paramdef>int <parameter>height</parameter></paramdef> + <paramdef>int <parameter>width</parameter></paramdef> + <paramdef>int <parameter>font_weight</parameter></paramdef> + <paramdef>bool <parameter>italic</parameter></paramdef> + <paramdef>bool <parameter>underline</parameter></paramdef> + <paramdef>bool <parameter>strikeout</parameter></paramdef> + <paramdef>int <parameter>orientaton</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function creates a new font and returns a handle to it. A font is + used to draw text. For an example see + <function>printer_select_font</function>. <parameter>face</parameter> + must be a string specifying the font face. <parameter>height</parameter> + specifies the font height, and <parameter>width</parameter> the font + width. The <parameter>font_weight</parameter> specifies the font weight + (400 is normal), and can be one of the following predefined constants. + <itemizedlist> + <listitem> + <simpara> + <parameter>PRINTER_FW_THIN</parameter>: + sets the font weight to thin (100). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FW_ULTRALIGHT</parameter>: + sets the font weight to ultra light (200). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FW_LIGHT</parameter>: + sets the font weight to light (300). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FW_NORMAL</parameter>: + sets the font weight to normal (400). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FW_MEDIUM</parameter>: + sets the font weight to medium (500). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FW_BOLD</parameter>: + sets the font weight to bold (700). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FW_ULTRABOLD</parameter>: + sets the font weight to ultra bold (800). + </simpara> + </listitem> + <listitem> + <simpara> + <parameter>PRINTER_FW_HEAVY</parameter>: + sets the font weight to heavy (900). + </simpara> + </listitem> + </itemizedlist> + <parameter>italic</parameter> can be &true; or &false;, and sets whether the font should be italic. + <parameter>underline</parameter> can be &true; or &false;, and sets whether the font should be underlined. + <parameter>strikeout</parameter> can be &true; or &false;, and sets whether the font should be striked out. + <parameter>orientation</parameter> specifies a rotation. + For an example see <function>printer_select_font</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.printer-delete-font"> + <refnamediv> + <refname>printer_delete_font</refname> + <refpurpose>Delete a font</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>printer_delete_font</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function deletes the selected font. For an example see + <function>printer_select_font</function>. It returns &true; on success, + or &false; otherwise. <parameter>handle</parameter> must be a valid + handle to a font. + </para> + </refsect1> + </refentry> + + <refentry id="function.printer-select-font"> + <refnamediv> + <refname>printer_select_font</refname> + <refpurpose>Select a font</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_select_font</function> + </funcdef> + <paramdef>resource <parameter>printer_handle</parameter></paramdef> + <paramdef>resource <parameter>font_handle</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function selects a font to draw text. + <parameter>printer_handle</parameter> must be a valid handle to a + printer. <parameter>font_handle</parameter> must be a valid handle + to a font. + </para> + <example> + <title> + <function>printer_select_font</function> example + </title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$font = printer_create_font("Arial", 148, 76, PRINTER_FW_MEDIUM, false, false, false, -50); +printer_select_font($handle, $font); +printer_draw_text($handle, "PHP is simply cool", 40, 40); +printer_delete_font($font); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-logical-fontheight"> + <refnamediv> + <refname>printer_logical_fontheight</refname> + <refpurpose>Get logical font height</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>printer_logical_fontheight</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>int <parameter>height</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function calculates the logical font height of + <parameter>height</parameter>. <parameter>handle</parameter> must + be a valid handle to a printer. + </para> + <example> + <title> + <function>printer_logical_fontheight</function> example + </title> + <programlisting role="php"> +$handle = printer_open(); +print printer_logical_fontheight($handle, 72); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-roundrect"> + <refnamediv> + <refname>printer_draw_roundrect</refname> + <refpurpose>Draw a rectangle with rounded corners</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_roundrect</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>int <parameter>ul_x</parameter></paramdef> + <paramdef>int <parameter>ul_y</parameter></paramdef> + <paramdef>int <parameter>lr_x</parameter></paramdef> + <paramdef>int <parameter>lr_y</parameter></paramdef> + <paramdef>int <parameter>width</parameter></paramdef> + <paramdef>int <parameter>height</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws a rectangle with rounded corners. + </para> + <para> + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <para> + <parameter>ul_x</parameter> is the upper left x coordinate of the rectangle. + </para> + <para> + <parameter>ul_y</parameter> is the upper left y coordinate of the rectangle. + </para> + <para> + <parameter>lr_x</parameter> is the lower right x coordinate of the rectangle. + </para> + <para> + <parameter>lr_y</parameter> is the lower right y coordinate of the rectangle. + </para> + <para> + <parameter>width</parameter> is the width of the ellipse. + </para> + <para> + <parameter>height</parameter> is the height of the ellipse. + </para> + <example> + <title> + <function>printer_draw_roundrect</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); +printer_select_pen($handle, $pen); + +$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); +printer_select_brush($handle, $brush); + +printer_draw_roundrect($handle, 1, 1, 500, 500, 200, 200); + +printer_delete_brush($brush); +printer_delete_pen($pen); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-rectangle"> + <refnamediv> + <refname>printer_draw_rectangle</refname> + <refpurpose>Draw a rectangle</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_rectangle</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>int <parameter>ul_x</parameter></paramdef> + <paramdef>int <parameter>ul_y</parameter></paramdef> + <paramdef>int <parameter>lr_x</parameter></paramdef> + <paramdef>int <parameter>lr_y</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws a rectangle. + </para> + <para> + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <para> + <parameter>ul_x</parameter> is the upper left x coordinate of the rectangle. + </para> + <para> + <parameter>ul_y</parameter> is the upper left y coordinate of the rectangle. + </para> + <para> + <parameter>lr_x</parameter> is the lower right x coordinate of the rectangle. + </para> + <para> + <parameter>lr_y</parameter> is the lower right y coordinate of the rectangle. + </para> + <example> + <title> + <function>printer_draw_rectangle</function> example + </title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); +printer_select_pen($handle, $pen); + +$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); +printer_select_brush($handle, $brush); + +printer_draw_rectangle($handle, 1, 1, 500, 500); + +printer_delete_brush($brush); +printer_delete_pen($pen); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-elipse"> + <refnamediv> + <refname>printer_draw_elipse</refname> + <refpurpose>Draw an ellipse</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_elipse</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>int <parameter>ul_x</parameter></paramdef> + <paramdef>int <parameter>ul_y</parameter></paramdef> + <paramdef>int <parameter>lr_x</parameter></paramdef> + <paramdef>int <parameter>lr_y</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws an ellipse. + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <para> + <parameter>ul_x</parameter> is the upper left x coordinate of the ellipse. + </para> + <para> + <parameter>ul_y</parameter> is the upper left y coordinate of the ellipse. + </para> + <para> + <parameter>lr_x</parameter> is the lower right x coordinate of the ellipse. + </para> + <para> + <parameter>lr_y</parameter> is the lower right y coordinate of the ellipse. + </para> + <example> + <title> + <function>printer_draw_elipse</function> example + </title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); +printer_select_pen($handle, $pen); + +$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); +printer_select_brush($handle, $brush); + +printer_draw_elipse($handle, 1, 1, 500, 500); + +printer_delete_brush($brush); +printer_delete_pen($pen); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-text"> + <refnamediv> + <refname>printer_draw_text</refname> + <refpurpose>Draw text</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_text</function> + </funcdef> + <paramdef>resource <parameter>printer_handle</parameter></paramdef> + <paramdef>string <parameter>text</parameter></paramdef> + <paramdef>int <parameter>x</parameter></paramdef> + <paramdef>int <parameter>y</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws <parameter>text</parameter> at position + <parameter>x</parameter>, <parameter>y</parameter> using the selected + font. <parameter>printer_handle</parameter> must be a valid handle to + a printer. + </para> + <example> + <title><function>printer_draw_text</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$font = printer_create_font("Arial",72,48,400,false,false,false,0); +printer_select_font($handle, $font); +printer_draw_text($handle, "test", 10, 10); +printer_delete_font($font); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-line"> + <refnamediv> + <refname>printer_draw_line</refname> + <refpurpose>Draw a line</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_line</function></funcdef> + <paramdef>resource <parameter>printer_handle</parameter></paramdef> + <paramdef>int <parameter>from_x</parameter></paramdef> + <paramdef>int <parameter>from_y</parameter></paramdef> + <paramdef>int <parameter>to_x</parameter></paramdef> + <paramdef>int <parameter>to_y</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws a line from position + <parameter>from_x</parameter>, <parameter>from_y</parameter> to + position <parameter>to_x</parameter>, <parameter>to_y</parameter> + using the selected pen. <parameter>printer_handle</parameter> must + be a valid handle to a printer. + </para> + <example> + <title><function>printer_draw_line</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, 000000"); +printer_select_pen($handle, $pen); + +printer_draw_line($handle, 1, 10, 1000, 10); +printer_draw_line($handle, 1, 60, 500, 60); + +printer_delete_pen($pen); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-chord"> + <refnamediv> + <refname>printer_draw_chord</refname> + <refpurpose>Draw a chord</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_chord</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>int <parameter>rec_x</parameter></paramdef> + <paramdef>int <parameter>rec_y</parameter></paramdef> + <paramdef>int <parameter>rec_x1</parameter></paramdef> + <paramdef>int <parameter>rec_y1</parameter></paramdef> + <paramdef>int <parameter>rad_x</parameter></paramdef> + <paramdef>int <parameter>rad_y</parameter></paramdef> + <paramdef>int <parameter>rad_x1</parameter></paramdef> + <paramdef>int <parameter>rad_y1</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws an chord. + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <para> + <parameter>rec_x</parameter> is the upper left x coordinate of the + bounding rectangle. + </para> + <para> + <parameter>rec_y</parameter> is the upper left y coordinate of the + bounding rectangle. + </para> + <para> + <parameter>rec_x1</parameter> is the lower right x coordinate of the + bounding rectangle. + </para> + <para> + <parameter>rec_y1</parameter> is the lower right y coordinate of + the bounding rectangle. + </para> + <para> + <parameter>rad_x</parameter> is x coordinate of the radial defining + the beginning of the chord. + </para> + <para> + <parameter>rad_y</parameter> is y coordinate of the radial defining + the beginning of the chord. + </para> + <para> + <parameter>rad_x1</parameter> is x coordinate of the radial defining + the end of the chord. + </para> + <para> + <parameter>rad_y1</parameter> is y coordinate of the radial defining + the end of the chord. + </para> + <example> + <title><function>printer_draw_chord</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); +printer_select_pen($handle, $pen); + +$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); +printer_select_brush($handle, $brush); + +printer_draw_chord($handle, 1, 1, 500, 500, 1, 1, 500, 1); + +printer_delete_brush($brush); +printer_delete_pen($pen); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-pie"> + <refnamediv> + <refname>printer_draw_pie</refname> + <refpurpose>Draw a pie</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_pie</function></funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>int <parameter>rec_x</parameter></paramdef> + <paramdef>int <parameter>rec_y</parameter></paramdef> + <paramdef>int <parameter>rec_x1</parameter></paramdef> + <paramdef>int <parameter>rec_y1</parameter></paramdef> + <paramdef>int <parameter>rad1_x</parameter></paramdef> + <paramdef>int <parameter>rad1_y</parameter></paramdef> + <paramdef>int <parameter>rad2_x</parameter></paramdef> + <paramdef>int <parameter>rad2_y</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws an pie. + <parameter>handle</parameter> must be a valid handle to a printer. + </para> + <para> + <parameter>rec_x</parameter> is the upper left x coordinate of + the bounding rectangle. + </para> + <para> + <parameter>rec_y</parameter> is the upper left y coordinate of + the bounding rectangle. + </para> + <para> + <parameter>rec_x1</parameter> is the lower right x coordinate of + the bounding rectangle. + </para> + <para> + <parameter>rec_y1</parameter> is the lower right y coordinate of + the bounding rectangle. + </para> + <para> + <parameter>rad1_x</parameter> is x coordinate of the first + radial's ending. + </para> + <para> + <parameter>rad1_y</parameter> is y coordinate of the first + radial's ending. + </para> + <para> + <parameter>rad2_x</parameter> is x coordinate of the second + radial's ending. + </para> + <para> + <parameter>rad2_y</parameter> is y coordinate of the second + radial's ending. + </para> + <example> + <title><function>printer_draw_chord</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000"); +printer_select_pen($handle, $pen); + +$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF"); +printer_select_brush($handle, $brush); + +printer_draw_pie($handle, 1, 1, 500, 500, 1, 1, 500, 1); + +printer_delete_brush($brush); +printer_delete_pen($pen); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.printer-draw-bmp"> + <refnamediv> + <refname>printer_draw_bmp</refname> + <refpurpose>Draw a bmp</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>printer_draw_bmp</function> + </funcdef> + <paramdef>resource <parameter>handle</parameter></paramdef> + <paramdef>string <parameter>filename</parameter></paramdef> + <paramdef>int <parameter>x</parameter></paramdef> + <paramdef>int <parameter>y</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + The function simply draws an bmp the bitmap + <parameter>filename</parameter> at position <parameter>x</parameter>, + <parameter>y</parameter>. <parameter>handle</parameter> must be a + valid handle to a printer. + </para> + <para> + The function returns &true; on success, or otherwise &false;. + </para> + <example> + <title><function>printer_draw_bmp</function> example</title> + <programlisting role="php"> +$handle = printer_open(); +printer_start_doc($handle, "My Document"); +printer_start_page($handle); + +printer_draw_bmp($handle, "c:\\image.bmp", 1, 1); + +printer_end_page($handle); +printer_end_doc($handle); +printer_close($handle); + </programlisting> + </example> + </refsect1> + </refentry> +</reference> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/es/chapters/install.xml diff -u phpdoc/es/chapters/install.xml:1.4 phpdoc/es/chapters/install.xml:1.5 --- phpdoc/es/chapters/install.xml:1.4 Wed Sep 13 12:41:59 2000 +++ phpdoc/es/chapters/install.xml Sat Jul 7 19:11:24 2001 @@ -1,1391 +1,1391 @@ - <chapter id="installation"> - <title>Instalación</title> - - <sect1 id="downloading"> - <title>Bajándose la última versión</title> - <simpara> - El código fuente y las distribuciones binarias para algunas - plataformas (incluído Windows) se pueden encontrar en <literal><ulink - url="http://www.php.net/">http://www.php.net/</ulink></literal>. - </simpara> - </sect1> - - <sect1 id="install-unix"> - <title>Instalación en sistemas UNIX</title> - - <para> - Esta sección le guiará a través de la configuración e - instalación del PHP. Conocimientos y software necesarios: - - <itemizedlist> - <listitem> - <simpara> - Habilidades básicas en UNIX (ser capaz de manejar el "make" - y un compilador de C) - </simpara> - </listitem> - <listitem> - <simpara> - Un compilador ANSI de C - </simpara> - </listitem> - <listitem> - <simpara> - Un servidor web - </simpara> - </listitem> - </itemizedlist> - </para> - - <sect2> - <title> - Instrucciones Rápidas de Instalación (Versión Módulo de Apache) - </title> - - <para> - <informalexample> - <programlisting> -1. gunzip apache_1.3.x.tar.gz -2. tar xvf apache_1.3.x.tar -3. gunzip php-3.0.x.tar.gz -4. tar xvf php-3.0.x.tar -5. cd apache_1.3.x -6. ./configure --prefix=/www -7. cd ../php-3.0.x -8. ./configure --with-mysql --with-apache=../apache_1.3.x --enable-track-vars -9. make -10. make install -11. cd ../apache_1.3.x -12. ./configure --prefix=/www --activate-module=src/modules/php3/libphp3.a -13. make -14. make install - - En lugar de este paso quizás prefiera simplemente copiar el binario - httpd encima del binario existente. Si lo hace, asegúrese antes de - cerrar su servidor. - -15. cd ../php-3.0.x -16. cp php3.ini-dist /usr/local/lib/php3.ini - - Puede editar el archivo /usr/local/lib/php3.ini para ajustar opciones - del PHP. Si prefiere tenerlo en otro sitio, utilice - --with-config-file-path=/path en el paso 8. - -17. Edite su archivo httpd.conf o srm.conf y añada: - - AddType application/x-httpd-php3 .php3 - - Puede elegir la extensión que desee aquí. .php3 es simplemente nuestra - sugerencia. - -18. Utilice su método habitual para iniciar el servidor Apache (debe detener - y reiniciar el servidor, no solamente hacerlo recargarse usando una - señal HUP o USR1.) - </programlisting> - </informalexample> - </para> - - </sect2> - - <sect2> - <title>Configuración</title> - <para> - Hay dos maneras de configurar el PHP. - <itemizedlist> - <listitem> - <para> - Utilizando el script de "setup" que viene con el PHP. Este - script le hace una serie de preguntas (casi como el script - "install" del PHP/FI 2.0) y ejecuta el "configure" al final. - Para ejecutar este script, escriba <command>./setup</command>. - </para> - <para> - Este script también creará un archivo llamado "do-conf", que - contendrá las opciones pasadas a la configuración. Puede editar - este archivo para cambiar algunas opciones sin tener que - re-ejecutar el "setup". Escriba luego <command>./do-conf</command> - para ejecutar la configuración con las nuevas opciones. - </para> - </listitem> - <listitem> - <para> - Ejecutar el "configure" a mano. Para ver las opciones de que - dispone, escriba <command>./configure --help</command>. - </para> - </listitem> - </itemizedlist> - </para> - <para> - Los detalles sobre las distintas opciones de configuración son - listados a continuación. - </para> - </sect2> - - <sect2 id="with-apache"> - <title>Módulo del Apache</title> - - <para> - Para configurar el PHP como módulo de Apache, responda "yes" a - "Build as an Apache module?" (la opción <option><link linkend="with-apache"> - --with-apache</link>=<replaceable>DIR</replaceable></option> - es la que lo configura) y especifique el directorio base de la - distribución de Apache. Si ha desempacado el Apache en - <filename - class="directory">/usr/local/www/apache_1.2.4</filename>, este será - su directorio base de la distribución de Apache. El directorio - por defecto es <filename - class="directory">/usr/local/etc/httpd</filename>. - </para> - </sect2> - - <sect2 id="with-fhttpd"> - <title>Módulo fhttpd</title> - - <para> - Para configurar el PHP como módulo fhttpd, responda "yes" a - "Build as an fhttpd module?" (la opción <option><link linkend="with-fhttpd"> - --with-fhttpd</link>=<replaceable>DIR</replaceable></option> - es la que lo configura) y especifique el directorio base - del fuente del fhttpd. El directorio por defecto es <filename - class="directory">/usr/local/src/fhttpd</filename>. Si está - ejecutando fhttpd, configurar PHP como módulo le dará mejor - rendimiento, más control y capacidad de ejecución remota. - </para> - </sect2> - - <sect2 id="install-cgi"> - <title>CGI version</title> - <para> - El valor por defecto es configurar el PHP como programa CGI. - Si está ejecutando un servidor web para el que el PHP tiene - soporte como módulo, debería elegir dicha solución por motivos - de rendimiento. Sin embargo, la versión CGI permite a los - usuarios del Apache el ejecutar distintas páginas con PHP bajo - distintos identificadores de usuario. Por favor, asegúrese - de haber leído el <link linkend="security">capítulo sobre - Seguridad</link> si va a ejecutar el PHP como CGI. - </para> - </sect2> - - <sect2> - <title>Opciones de soporte para Base de Datos</title> - <para> - El PHP tiene soporte nativo para bastantes bases de datos - (así como para ODBC): - </para> - - <sect3 id="with-adabas"> - <title>Adabas D</title> - <synopsis> - <option>--with-adabas<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Compila con soporte para Adabas D. El parámetro es el directorio - de instalación de Adabas D y por defecto vale <filename - class="directory">/usr/local/adabasd</filename>. - </simpara> - <simpara> - <ulink url="http://www.adabas.com/">Página de Adabas</ulink> - </simpara> - </sect3> - - <sect3 id="with-dbase"> - <title>dBase</title> - <synopsis> - <option>--with-dbase</option> - </synopsis> - <simpara> - Habilita el soporte integrado para DBase. No se precisan librerías - externas. - </simpara> - </sect3> - - <sect3 id="with-filepro"> - <title>filePro</title> - <synopsis> - <option>--with-filepro</option> - </synopsis> - <simpara> - Habilita el soporte integrado de sólo lectura para filePro. No se - precisan librerías externas. - </simpara> - </sect3> - - <sect3 id="with-msql"> - <title>mSQL</title> - <synopsis> - <option>--with-msql<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Habilita el soporte para mSQL. El parámetro es el directorio - de instalación de mSQL y por defecto vale <filename - class="directory">/usr/local/Hughes</filename>. Este es el - directorio por defecto de la distribución mSQL 2.0. - <command>configure</command> detecta automáticamente qué versión - de mSQL está ejecutándose y el PHP soporta tanto 1.0 como 2.0, pero - si compila el PHP con mSQL 1.0 sólo podrá acceder a bases de datos - de esa versión y viceversa. - </simpara> - <simpara> - Vea también Directivas de <link linkend="ini.sect.msql">Configuración - de mSQL</link> en el <link linkend="configuration.file">archivo de - configuración</link>. - </simpara> - <simpara> - <ulink url="http://www.hughes.com.au">Página de mSQL</ulink> - </simpara> - </sect3> - - <sect3 id="with-mysql"> - <title>MySQL</title> - <synopsis> - <option>--with-mysql<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Habilita el soporte para MySQL. El parámetro es el directorio - de instalación de MySQL y por defecto vale <filename - class="directory">/usr/local</filename>. Este es el directorio - de instalación de la distribución de MySQL. - </simpara> - <simpara> - Vea también Directivas de <link linkend="ini.sect.mysql">Configuración - de MySQL</link> en el <link linkend="configuration.file">archivo de - configuración</link>. - </simpara> - <simpara> - <ulink url="http://www.tcx.se">Página de MySQL</ulink> - </simpara> - </sect3> - - <sect3 id="with-iodbc"> - <title>iODBC</title> - <synopsis> - <option>--with-iodbc<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para iODBC. Esta característica se desarrolló - inicialmente para el iODBC Driver Manager, un gestor de controlador - de ODBC de redistribución libre que ese ejecuta bajo varios - sabores de UNIX. El parámetro es el directorio de instalación - de iODBC y por defecto vale <filename class="directory">/usr/local</filename>. - </simpara> - <simpara> - <ulink url="http://users.ids.net/~bjepson/freeODBC/">Página de - FreeODBC</ulink> o <ulink url="http://www.iodbc.org">página de - iODBC</ulink> - </simpara> - </sect3> - - <sect3 id="with-openlink"> - <title>OpenLink ODBC</title> - <synopsis> - <option>--with-openlink<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para OpenLink ODBC. El parámetro es el directorio - de instalación de OpenLink ODBC y por defecto vale - <filename class="directory">/usr/local/openlink</filename>. - </simpara> - <simpara> - <ulink url="http://www.openlinksw.com/">Página de OpenLink Software</ulink> - </simpara> - </sect3> - - <sect3 id="with-oracle"> - <title>Oracle</title> - <synopsis> - <option>--with-oracle<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para Oracle. Se ha probado y debería funcionar al - menos con las versiones de la 7.0 a la 7.3. El parámetro es el - directorio <envar>ORACLE_HOME</envar>. No necesita especificar - este parámetro si su entorno de Oracle ya está ajustado.</simpara> - <simpara> - <ulink url="http://www.oracle.com">Página de Oracle</ulink> - </simpara> - </sect3> - - <sect3 id="with-pgsql"> - <title>PostgreSQL</title> - <synopsis> - <option>--with-pgsql<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para PostgreSQL. El parámetro es el directorio - base de la instalación de PostgreSQL y por defecto vale <filename - class="directory">/usr/local/pgsql</filename>. - </simpara> - <simpara> - Vea también Directivas de <link linkend="ini.sect.pgsql">Configuración - de Postgres</link> en el <link - linkend="configuration.file">archivo de configuración</link>. - </simpara> - <simpara> - <ulink url="http://www.postgreSQL.org/">Página de PostgreSQL</ulink> - </simpara> - </sect3> - - <sect3 id="with-solid"> - <title>Solid</title> - <synopsis> - <option>--with-solid<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para Solid. El parámetro es el directorio de - instalación y vale por defecto <filename - class="directory">/usr/local/solid</filename>. - </simpara> - <simpara> - <ulink url="http://www.solidtech.com">Página de Solid</ulink> - </simpara> - </sect3> - - <sect3 id="with-sybase"> - <title>Sybase</title> - <synopsis> - <option>--with-sybase<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para Sybase. El parámetro es el directorio de - instalación y vale por defecto <filename - class="directory">/home/sybase</filename>. - </simpara> - <simpara> - Vea también Directivas de <link linkend="ini.sect.sybase">Configuración - de Sybase</link> en el <link - linkend="configuration.file">archivo de configuración</link>. - </simpara> - <simpara> - <ulink url="http://www.sybase.com">Página de Sybase</ulink> - </simpara> - </sect3> - - <sect3 id="with-sybase-ct"> - <title>Sybase-CT</title> - <synopsis> - <option>--with-sybase-ct<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para Sybase-CT. El parámetro es el directorio - de instalación de Sybase-CT y por defecto vale <filename - class="directory">/home/sybase</filename>. - </simpara> - <simpara> - Vea también Directovas de <link linkend="ini.sect.sybct">Configuración - de Sybase-CT</link> en el <link - linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="with-velocis"> - <title>Velocis</title> - <synopsis> - <option>--with-velocis<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para Velocis. El parámetro es el directorio de - instalación de Velocis y vale por defecto <filename - class="directory">/usr/local/velocis</filename>. - </simpara> - <simpara> - <ulink url="http://www.raima.com">Página de Velocis</ulink> - </simpara> - </sect3> - - <sect3 id="with-custom-odbc"> - <title>Una librería a medida de ODBC</title> - <synopsis> - <option>--with-custom-odbc<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para una librería a medida arbitraria de ODBC. - El parámetro es el directorio base y por defecto vale <filename - class="directory">/usr/local</filename>. - </simpara> - <simpara> - Esta opción implica que se ha definido CUSTOM_ODBC_LIBS cuando se - ejecutó el script de configuración. También deberá tener una - cabecera odbc.h válida en algún lugar de su sendero (path) de - inclusión. Si no tiene uno, créelo e incluya su cabecera específica - desde ahí. Su cabecera puede requerir algunas definiciones extra, - particularmente si es multiplataforma. Defínalas en CFLAGS.</simpara> - <simpara> - Por ejemplo, puede usar Sybase SQL Anywhere bajo QNX como - sigue: - <literal> - CFLAGS=-DODBC_QNX LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib - -lodbc" ./configure --with-custom-odbc=/usr/lib/sqlany50 - </literal> - </simpara> - </sect3> - - <sect3 id="disable-unified-odbc"> - <title>ODBC Unificado</title> - <synopsis> - <option>--disable-unified-odbc</option> - </synopsis> - <simpara> - Deshabilita el módulo de ODBC Unificado, que es un interfaz común - a todas las bases de datos con interfaces basados en ODBC, tales - como Solid y Adabas D. También funciona para librerías normales - de ODBC. Ha sido probado con iODBC, Solid, Adabas D y Sybase SQL - Anywhere. Requiere que uno (y sólo uno) de estos módulos o el - módulo de Velocis esté habilitado, o que se especifique una librería - a medida de ODBC. Esta opción sólo se puede aplicar si alguna de - estas opciones es usada: <link - linkend="with-iodbc">--with-iodbc</link>, <link - linkend="with-solid">--with-solid</link>, <link - linkend="with-adabas">--with-adabas</link>, <link - linkend="with-velocis">--with-velocis</link>, o <link - linkend="with-adabas">--with-custom-odbc</link>. - </simpara> - <simpara> - Vea también Directivas de <link linkend="ini.sect.uodbc">Configuración - de ODBC Unificado</link> en el <link - linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="with-ldap"> - <title>LDAP</title> - <synopsis> - <option>--with-ldap<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Incluye soporte para <acronym>LDAP</acronym> (Lightweight - Directory Access Protocol - Protocolo Ligero de Acceso a - Directorios). El parámetro es el directorio base de instalación - de LDAP, y por defecto vale <filename - class="directory">/usr/local/ldap</filename>. - </simpara> - <simpara> - Puede encontrar más información sobre LDAP en <ulink - url="ftp://ftp.isi.edu/in-notes/rfc1777.txt">RFC1777</ulink> y en - <ulink - url="ftp://ftp.isi.edu/in-notes/rfc1778.txt">RFC1778</ulink>. - </simpara> - </sect3> - - </sect2> - - <sect2> - <title>Otras opciones de configuración</title> - - <sect3 id="with-mcrypt"> - <title>--with-mcrypt<replaceable>=DIR</replaceable></title> - <synopsis> - <option>--with-mcrypt</option> - </synopsis> - <simpara> - Incluye soporte para la librería mcrypt. Vea la <link - linkend="ref.mcrypt">documentación de mcrypt</link> para - más información. Si utiliza el argumento opcional - <replaceable>DIR</replaceable>, el PHP buscará mcrypt.h - en <replaceable>DIR</replaceable>/include. - </simpara> - </sect3> - - <sect3 id="enable-sysvsem"> - <title>--enable-sysvsem</title> - <synopsis> - <option>--enable-sysvsem</option> - </synopsis> - <simpara> - Incluye soporte para semáforos Sys V (soportados por muchos - derivados Unix). Vea la <link linkend="ref.sem">documentación - sobre Semáforos y Memoria Compartida</link> para más información. - </simpara> - </sect3> - - <sect3 id="enable-sysvshm"> - <title>--enable-sysvshm</title> - <synopsis> - <option>--enable-sysvshm</option> - </synopsis> - <simpara> - Incluye soporte para la memoria compartida Sys V (soportada por - muchos derivados Unix). Vea la <link linkend="ref.sem">documentación - sobre Semáforos y Memoria Compartida</link> para más información. - </simpara> - </sect3> - - <sect3 id="with-xml"> - <title>--with-xml</title> - <synopsis> - <option>--with-xml</option> - </synopsis> - <simpara> - Incluye soporte para un parser XML no validador que utiliza - la <ulink url="&url.expat;">librería expat</ulink> de James Clark. - Vea la <link linkend="ref.xml">referencia de funciones XML</link> - para más detalles. - </simpara> - </sect3> - - <sect3 id="enable-maintainer-mode"> - <title>--enable-maintainer-mode</title> - <synopsis> - <option>--enable-maintainer-mode</option> - </synopsis> - <simpara> - Activa avisos extra de dependencias y del compilador utilizados - por algunos de los desarrolladores del PHP.</simpara> - </sect3> - - <sect3 id="with-system-regex"> - <title>--with-system-regex</title> - <synopsis> - <option>--with-system-regex</option> - </synopsis> - <simpara> - Utiliza la librería de expresiones regulares del sistema en - lugar de la incluída. Si está compilando PHP como módulo de - servidor, debe utilizar la misma librería cuando genere el - PHP y cuando lo enlace con el servidor. Active esto si la - librería del sistema proporciona características especiales - que pueda necesitar. Se recomienda utilizar la librería - incluída siempre que sea posible.</simpara> - </sect3> - - <sect3 id="with-config-file-path"> - <title>--with-config-file-path</title> - <synopsis> - <option>--with-config-file-path=DIR</option> - </synopsis> - <simpara> - El path utilizado para buscar <link linkend="configuration.file">el - archivo de configuración</link> cuando arranca el PHP. - </simpara> - </sect3> - - <sect3 id="with-exec-dir"> - <title>--with-exec-dir</title> - <synopsis> - <option>--with-exec-dir<replaceable>=DIR</replaceable></option> - </synopsis> - <simpara> - Sólo permite ejecutar programas en DIR cuando está en modo - seguro. Por defecto vale <filename class="directory">/usr/local/bin</filename>. - Esta opción sólo fija el valor por defecto. Puede ser cambiado - posteriormente mediante la directiva - <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link> - en el <link linkend="configuration.file">fichero de configuración - </link>. - </simpara> - </sect3> - - <sect3 id="enable-debug"> - <title>--enable-debug</title> - <synopsis> - <option>--enable-debug</option> - </synopsis> - <simpara> - Habilita información de depuración adicional. Esto hace posible - obtener información más detallada cuando hay problemas con el PHP. - (Nótese que esto no tiene que ver con las facilidades de depuración - o con la información disponible para los script PHP). - </simpara> - </sect3> - - <sect3 id="enable-safe-mode"> - <title>--enable-safe-mode</title> - <synopsis> - <option>--enable-safe-mode</option> - </synopsis> - <simpara> - Habilita el "modo seguro" por defecto. Esto impone varias - restricciones sobre lo que el PHP puede hacer, tales como - abrir fichero sólo en el raiz de documentos. Lea el <link - linkend="security">capítulo de Seguridad</link> para más - información. Los usuarios de CGI deberán siempre habilitar - el modo seguro. Esta opción sólo fija el valor por defecto. - Puede ser habilitado o deshabilitado posteriormente mediante - la directiva <link linkend="ini.safe-mode">safe_mode</link> en - el <link linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="enable-track-vars"> - <title>--enable-track-vars</title> - <synopsis> - <option>--enable-track-vars</option> - </synopsis> - <simpara> - Hace que el PHP lleve el control de dónde proceden las variables - GET/POST/cookie usando las matrices HTTP_GET_VARS, HTTP_POST_VARS - y HTTP_COOKIE_VARS. Esta opción sólo fija el valor por defecto. - Puede ser habilitado o deshabilitado posteriormente mediante la - directiva <link - linkend="ini.track-vars">track_vars</link> en el - <link linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="enable-magic-quotes"> - <title>--enable-magic-quotes</title> - <synopsis> - <option>--enable-magic-quotes</option> - </synopsis> - <simpara> - Habilita las comillas mágicas por defecto. Esta opción sólo - fija el valor por defecto. Puede ser habilitada o deshabilitada - posteriormente mediante la directiva <link - linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link> - en el <link - linkend="configuration.file">archivo de configuración</link>. - Vea también las directivas <link linkend="ini.magic-quotes-gpc"> - magic_quotes_gpc</link> y <link - linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>. - </simpara> - </sect3> - - <sect3 id="enable-debugger"> - <title>--enable-debugger</title> - <synopsis> - <option>--enable-debugger</option> - </synopsis> - <simpara> - Habilita el soporte de depuración interno del PHP. Esta - característica aún está en estado experimental. Vea también - las directivas de <link linkend="ini.sect.debugger">Configuración - del Depurador</link> en el <link - linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="enable-discard-path"> - <title>--enable-discard-path</title> - <synopsis> - <option>--enable-discard-path</option> - </synopsis> - <simpara> - Si está habilitado, el ejecutable CGI del PHP se puede situar - tranquilamente fuera del árbol de la web y la gente no podrá - saltarse la seguridad del .htaccess. Lea la <link - linkend="security.cgi.shell">sección en el capítulo de - seguridad</link> sobre esta opción. - </simpara> - </sect3> - - <sect3 id="enable-bcmath"> - <title>--enable-bcmath</title> - <synopsis> - <option>--enable-bcmath</option> - </synopsis> - <simpara> - Habilita las funciones matemáticas de precisión arbitraria - estilo <command>bc</command>. Vea también la opción <link - linkend="ini.sect.bcmath">bcmath.scale </link> en el - <link linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="enable-force-cgi-redirect"> - <title>--enable-force-cgi-redirect</title> - <synopsis> - <option>--enable-force-cgi-redirect</option> - </synopsis> - <simpara> - Habilita la comprobación de seguridad para redirecciones internas - del servidor. Deberá usar esta opción si está ejecutando la - versión CGI bajo Apache. - </simpara> - <simpara> - Cuando se utiliza el PHP como un ejecutable CGI, siempre - comprueba primero is está siendo utilizado bajo redirección - (por ejemplo bajo Apache, usando directivas Action). Esto - asegura que el ejecutable del PHP no se puede usar para saltarse - los mecanismos estánder de autentificación del servidor web - llamando al ejecutale directamente, como en <filename - role="url">http://my.host/cgi-bin/php/secret/doc.html</filename>. - Este ejemplo accede al archivo <filename - role="url">http://my.host/secret/doc.html</filename> pero sin - respetar ningún ajuste de seguridad del httpd para el directorio - <filename role="dir">/secret</filename>. - </simpara> - <simpara> - No habilitando esta opción se deshabilita la comprobación y - se permite el saltarse los ajustes de seguridad y autenticación - del httpd. Haga esto sólo si el software de su servidor no - puede indicar que se ha realizado una redirección segura y - que todos sus archivos bajo la raiz de documentos y los - directorios de los usuarios pueden ser accedidos por cualquiera. - </simpara> - <simpara> - Lea la <link linkend="security.cgi.force-redirect">sección en - el capítulo de seguridad</link> acerca de esta opción. - </simpara> - </sect3> - - <sect3 id="disable-short-tags"> - <title>--disable-short-tags</title> - <synopsis> - <option>--disable-short-tags</option> - </synopsis> - <simpara> - Deshabilita las etiquetas de PHP en formato corto <literal>&lt;? ?&gt;</literal>. - Debe deshabilitar el formato corto si desea usar PHP con - <acronym>XML</acronym>. Con el formato corto deshabilitado, la - única etiqueta de código de PHP es <literal>&lt;?php ?&gt;</literal>. - Esta opción sólo fija el valor por defecto. Puede ser habilitada o - deshabilitada posteriormente mediante la directiva <link - linkend="ini.short-open-tag">short_open_tag</link> en el <link - linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="enable-url-includes"> - <title>--enable-url-includes</title> - <synopsis> - <option>--enable-url-includes</option> - </synopsis> - <simpara> - Hace posible ejecutar código en otros servidores HTTP o FTP - directamente desde el PHP usando <link - linkend="function.include">include()</link>. Vea también la - opción <link - linkend="ini.include-path">include_path</link> en el - <link linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect3> - - <sect3 id="disable-syntax-hl"> - <title>--disable-syntax-hl</title> - <synopsis> - <option>--disable-syntax-hl</option> - </synopsis> - <simpara> - Desconecta el resalte de sintáxis. - </simpara> - </sect3> - - <sect3> - <title>CPPFLAGS y LDFLAGS</title> - <para> - Para hacer que la instalación de PHP busque los archivos de cabecera - o de librería en distintos directorios, modifique las variables de - entorno <envar>CPPFLAGS</envar> y <envar>LDFLAGS</envar> respectivamente. - Si está utilizando un shell "sensible", podrá ejecutar - <command> - LDFLAGS=-L/my/lib/dir CPPFLAGS=-I/my/include/dir ./configure - </command> - </para> - </sect3> - - </sect2> - - <sect2> - <title>Construyendo</title> - <simpara> - Cuando el PHP está configurado, ya está listo para construir el - ejecutable CGI o la librería PERL. El comando <command>make</command> - debería ocuparse de esto. Si fallara y no puede saber el motivo, vea - la <link linkend="install-problems">sección de Problemas</link>. - </simpara> - </sect2> - - <sect2> - <title>Probando</title> - <simpara> - Si ha construído el PHP como un programa CGI, puede probar su - funcionamiento tecleando <command>make test</command>. Siempre es - buena idea probar su construcción. Así puede atrapar pronto - los problemas del PHP en su plataforma sin tener que batallar - con ellos luego. - </simpara> - </sect2> - - <sect2> - <title>Comprobando la velocidad</title> - <simpara> - Si ha construído el PHP como un programa CGI, puede comprobar - la velocidad de su código escribiendo <command>make bench</command>. - Nótese que se el modo seguro está habilitado por defecto, el test - no podrá finalizar si se toma más de los 30 segundos disponibles. - Esto se debe a que la función <function>set_time_limit</function> - no se puede usar en modo seguro. Use el ajuste de configuración <link - linkend="ini.max-execution-time">max_execution_time</link> - para controlar este tiempo en sus propios script. - <command>make bench</command> ignora el <link - linkend="configuration.file">archivo de configuración</link>. - </simpara> - </sect2> - - </sect1> - - <sect1 id="install-windows95-nt"> - <title>Instalación en sistemas Windows 95/98/NT</title> - - <simpara> - Esta guía de instalación le ayudará a instalar y configurar el PHP - en sus servidores web bajo Windows 9x/NT. Esta guía fue compilada - por &link.bob;. La última revisión puede encontrarse en <ulink - url="&url.win32install">&url.win32install</ulink>. - </simpara> - <para> - Esta guía proporciona soporte de instalacion para: - <itemizedlist> - <listitem> - <para> - Personal Web Server (se recomienda la última versión) - </para> - </listitem> - <listitem> - <para> - Internet Information Server 3 ó 4 - </para> - </listitem> - <listitem> - <para> - Apache 1.3.x - </para> - </listitem> - <listitem> - <para> - Omni HTTPd 2.0b1 - </para> - </listitem> - </itemizedlist> - </para> - - <sect2> - <title>Pasos Generales de Instalación</title> - - <para> - Los siguientes pasos deben realizarse en todas las instalaciones - antes de las instrucciones específicas de cada servidor. - - <itemizedlist> - <listitem> - <para> - Extraiga el archivo de distribución a un directorio de su - elección. "C:\PHP3\" es un buen comienzo. - </para> - </listitem> - <listitem> - <para> - Copie el archivo 'php3.ini-dist' a su directorio '%WINDOWS%' - y renómbrelo a 'php3.ini'. Su directorio '%WINDOWS%' es - típicamente: - <simplelist> - <member>c:\windows para Windows 95/98</member> - <member>c:\winnt o c:\winnt40 para servidores NT</member> - </simplelist> - </para> - </listitem> - <listitem> - <para> - Edite su archivo 'php3.ini': - <itemizedlist> - <listitem> - <simpara> - Necesitaá cambiar la opción 'extension_dir' para que apunte - a su php-install-dir, o a donde quiera que haya puesto - sus archivos 'php3_*.dll'. P.ej.: c:\php3 - </simpara> - </listitem> - <listitem> - <simpara> - Si está utilizando Omni Httpd, no siga el siguiente paso. - Fije el 'doc_root' para que apunte a la raiz web de sus - servidores. P.ej.: c:\apache\htdocs o c:\webroot - </simpara> - </listitem> - <listitem> - <simpara> - Elija qué módulos desearía cargar cuando comience el PHP. - Puede descomentar las líneas: 'extension=php3_*.dll' para - cargar estos módulos. Algunos módulos requieren que tenga - instaladas en sus sistema librerías adicionales para que - el módulo funcione correctamente. El <ulink - url="&url.php.faq">FAQ</ulink> de PHP tiene más información - sobre dónde obtener librerías de soporte. También puede - cargar un módulo dinámicamente en su script utilizando: - <command>dl("php_*.dll");</command> - </simpara> - </listitem> - <listitem> - <simpara> - En el PWS y el IIS puede fijar el browscap.ini para que apunte - a: 'c:\windows\system\inetsrv\browscap.ini' bajo Windows 95/98 - y a 'c:\winnt\system32\inetsrv\browscap.ini' bajo NT - Server. Se puede encontrar información adicional sobre el uso - de la funcionalidad del browscap en el PHP en este <ulink - url="&url.browscap;">servidor alternativo</ulink>. Elija el - botón "fuente" para verlo en acción. - </simpara> - </listitem> - </itemizedlist> - </para> - </listitem> - </itemizedlist></para> - <simpara> - Las DLL para las extensiones del PHP van precedidas de 'php3_'. - Esto evita confusiones entre las extensiones del PHP y sus - librerías de soporte. - </simpara> - - </sect2> - - <sect2> - <title>Windows 95/98/NT y PWS/IIS 3</title> - - <simpara> - El método recomendado para configurar estos servidores es usar - el archivo INF incluído con la distribución (php_iis_reg.inf). - Quizás desee editar este archivo y asegurarse que las extensiones - y directorios de instalación se ajustan a su configuración. O puede - seguir los pasos que siguen para hacerlo de forma manual. - </simpara> - <simpara> - AVISO: Estos pasos conllevan el trabajar directamente con el - registro de windows. Un error aquí puede dejar su sistema en - un estado inestable. Le recomendamos encarecidamente que haga - una copia de seguridad del registro con antelación. El equipo - de Desarrollo del PHP no se hará responsable si se daña su - registro. - </simpara> - - <para> - <itemizedlist> - <listitem> - <simpara> - Ejecute Regedit. - </simpara> - </listitem> - <listitem> - <simpara> - Navegue hasta: <literal>HKEY_LOCAL_MACHINE /System - /CurrentControlSet /Services /W3Svc /Parameters - /ScriptMap</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - En el menú de edición elija: <literal>New->String Value</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Escriba la extensión que desea usar para sus script - PHP. P.ej.: <literal>.php3</literal> - </simpara> - </listitem> - <listitem> - <simpara> - Haga doble click en el nuevo valor de cadena y escriba la - ruta al <literal>php.exe</literal> en el campo del valor. - P.ej.: <literal>c:\php3\php.exe %s %s</literal>. La parte '%s %s' - son MUY importantes, pues el PHP no funcionará correctamente - sin ella. - </simpara> - </listitem> - <listitem> - <simpara> - Repita estos pasos para cada extensión que desee asociar con - los scripts PHP. - </simpara> - </listitem> - <listitem> - <simpara> - Ahora navegue hasta: <literal>HKEY_CLASSES_ROOT</literal> - </simpara> - </listitem> - <listitem> - <simpara> - En el menú de edición elija: <literal>New->Key</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Déle a la clave el nombre de la extensión que preparó - en la sección anterior. P.ej.: <literal>.php3</literal> - </simpara> - </listitem> - <listitem> - <simpara> - Marque la nueva clave y en el panel del lado derecho haga - doble click en "default value" y escriba <literal>phpfile</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Repita el último paso para cada extensión que haya preparado - en la sección previa. - </simpara> - </listitem> - <listitem> - <simpara> - Ahora cree otra <literal>New->Key</literal> bajo - <literal>HKEY_CLASSES_ROOT</literal> y denomínela - <literal>phpfile</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Marque la nueva clave <literal>phpfile</literal> y haga doble - click en el panel derecho sobre "default value" y escriba - <literal>PHP Script</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Pulse el botón derecho sobre la clave <literal>phpfile</literal> - y seleccione <literal>New->Key</literal> y llámela <literal>Shell</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Pulse el botón derecho sobre la clave <literal>Shell</literal> - y elija <literal>New->Key</literal> y llámela <literal>open</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Pulse el botón derecho sobre la clave <literal>open</literal> - y elija <literal>New->Key</literal> y llámela - <literal>command</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Marque la nueva clave <literal>command</literal> y en el panel - derecho haga doble click sobre "default value" y entre la ruta - hasta el <literal>php.exe</literal>. P.ej.: - <literal>c:\php3\php.exe -q %1</literal>. (no olvide el - <literal>%1</literal>). - </simpara> - </listitem> - <listitem> - <simpara> - Salga del Regedit. - </simpara> - </listitem> - </itemizedlist> - </para> - <simpara> - Los usuarios de PWS e IIS3 tienen ahora un sistema completamente - operativo. Los usuarios del IIS3 también pueden usar una curiosa - <ulink url="http://www.genusa.com/iis/iiscfg.html">herramienta</ulink> - de Steven Genusa para configurar sus mapeados de script. - </simpara> - - </sect2> - - <sect2> - <title>Windows NT e IIS 4</title> - - <simpara> - Para instalar el PHP en un NT Server con IIS 4, siga estas - instrucciones: - </simpara> - - <para> - <itemizedlist> - <listitem> - <simpara> - En el Controlador de Servicios de Internet (MMC), elija el sitio - Web o el directorio de comienzo de una aplicación. - </simpara> - </listitem> - <listitem> - <simpara> - Abra las propiedades del directorio (haciendo click derecho y - eligiendo propiedades) y luego pulse sobre la pestaña Carpeta - Inicial, Directorio Virtual o Directorio. - </simpara> - </listitem> - <listitem> - <simpara> - Pulse el botón Configuración y luego pulse sobre la pestaña - Mapas de Aplicación. - </simpara> - </listitem> - <listitem> - <simpara> - Pulse en Añadir, y en la caja Programa, escriba: - <literal>c:\path-to-php-dir\php.exe %s %s</literal>. DEBE - mantene los %s %s al final, pues el PHP no funcionará - correctamente si se equivoca al hacerlo. - </simpara> - </listitem> - <listitem> - <simpara> - En la caja Extensión, escriba la extensión de fichero que desea - asociar a los script de PHP. Debe repetir los pasos 5 y 6 para - cada extensión que desee asociar con los scripts PHP ( - <literal>.php3</literal> y <literal>.phtml</literal> son - habituales). - </simpara> - </listitem> - <listitem> - <simpara> - Ajuste la seguridad apropiada (esto se realiza en el Controlador - de Servicio de Internet (ISM)), y si su NT Server usa el sistema - de archivos NTFS, añada derechos de ejecución para I_USR_ al - directorio que contenga el <literal>php.exe</literal>. - </simpara> - </listitem> - </itemizedlist> - </para> - - </sect2> - - <sect2> - <title>Windows 9x/NT y Apache 1.3.x</title> - - <simpara> - Debe editar sus archivos <literal>srm.conf</literal> o - <literal>httpd.conf</literal> para configurar el Apache - para que trabaje con el ejecutable CGI del PHP. - </simpara> - <simpara> - Aunque puede haber algunas variaciones al configurar PHP bajo - Apache, esta es lo suficientemente simple para ser usada por - el novato. Por favor, consulte la Documentación del Apache para - saber de las subsiguientes directivas de configuración. - </simpara> - - <para> - <itemizedlist> - <listitem> - <simpara> - <literal> - ScriptAlias /php3/ "c:/ruta-al-dir-del-php/" - </literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal> - AddType application/x-httpd-php3 .php3 - </literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal> - AddType application/x-httpd-php3 .phtml - </literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal> - Action application/x-httpd-php3 "/php3/php.exe" - </literal> - </simpara> - </listitem> - </itemizedlist> - </para> - - <simpara> - Para utilizar la capacidad de marcado del código fuente, cree - simplemente un script de PHP y pegue este código en él: - <literal>&lt;?php show_source("script_original_php.php3"); ?></literal>. - Sustituya <literal>script_original_php.php3</literal> por el nombre - del archivo del que desea visualizar el código fuente (esta es la - única forma de hacerlo). - <emphasis>Nota:</emphasis> Bajo Win-Apache todas las barras - invertidas de una ruta tal como: "c:\directory\file.ext", - deben ser convertidas a barras hacia adelante. - </simpara> - - </sect2> - - <sect2> - <title>Omni HTTPd 2.0b1 para Windows</title> - - <simpara> - Esta ha resultado ser la configuración más sencilla: - </simpara> - - <para> - <simplelist> - <member> - Paso 1: Instale el servidor Omni - </member> - <member> - Paso 2: Pulse el botón derecho sobre el icono azul - del OmniHTTPd que está en la barrita del sistema y elija - <literal>Propiedades</literal> - </member> - <member> - Paso 3: Pulse sobre <literal>Web Server Global - Settings</literal> - </member> - <member> - Paso 4: En la pestaña 'External', escriba: <literal>virtual = .php3 - | actual = c:\ruta-al-dir-del-php\php.exe</literal> - </member> - <member> - Paso 5: En la pestaña <literal>Mime</literal>, escriba: - <literal>virtual = wwwserver/stdcgi | actual = .php3</literal> - </member> - <member> - Paso 6: Pulse en <literal>OK</literal> - </member> - </simplelist> - </para> - - <simpara> - Repita los pasos 2 a 6 para cada extensión que desee asociar - al PHP. - </simpara> - - </sect2> - - <sect2> - <title>Módulos del PHP</title> - - <para> - <table> - <title>Módulos del PHP</title> - <tgroup cols="2"> - <tbody> - <row> - <entry>php3_calendar.dll</entry> - <entry>Funciones de conversión de calendario</entry> - </row> - <row> - <entry>php3_crypt.dll</entry> - <entry>Funciones de criptografía</entry> - </row> - <row> - <entry>php3_dbase.dll</entry> - <entry>Funciones para DBase</entry> - </row> - <row> - <entry>php3_dbm.dll</entry> - <entry>Emulación GDBM con la librería Berkeley DB2</entry> - </row> - <row> - <entry>php3_filepro.dll</entry> - <entry>Acceso SÓLO LECTURA a bases de datos filepro</entry> - </row> - <row> - <entry>php3_gd.dll</entry> - <entry>Funciones de librería GD para manipular GIF</entry> - </row> - <row> - <entry>php3_hyperwave.dll</entry> - <entry>Funciones de HyperWave</entry> - </row> - <row> - <entry>php3_imap4r2.dll</entry> - <entry>Funciones de IMAP 4</entry> - </row> - <row> - <entry>php3_ldap.dll</entry> - <entry>Funciones de LDAP</entry> - </row> - <row> - <entry>php3_msql1.dll</entry> - <entry>Cliente de mSQL 1</entry> - </row> - <row> - <entry>php3_msql2.dll</entry> - <entry>Cliente de mSQL 2</entry> - </row> - <row> - <entry>php3_mssql.dll</entry> - <entry>Cliente de MSSQL client (requiere las librerías de MSSQL DB</entry> - </row> - <row> - <entry>php3_mysql.dll</entry> - <entry>Funciones de MySQL</entry> - </row> - <row> - <entry>php3_nsmail.dll</entry> - <entry>Funciones de correo de Netscape</entry> - </row> - <row> - <entry>php3_oci73.dll</entry> - <entry>Funciones de Oracle</entry> - </row> - <row> - <entry>php3_snmp.dll</entry> - <entry>Funciones get y walk de SNMP (¡sólo en NT!)</entry> - </row> - <row> - <entry>php3_zlib.dll</entry> - <entry>Funciones de ZLib</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - - </sect2> - - </sect1> - - <sect1 id="install-problems"> - <title>¿Problemas?</title> - - <sect2> - <title>Lea las PMF (FAQ)</title> - <simpara> - Algunos problemas son más comunes que otros. Los más comunes están - listados en las PMF (Preguntas Más Frecuentes) del PHP, que están - en <ulink url="&url.php.faq;">&url.php.faq;</ulink> - </simpara> - </sect2> - - <sect2> - <title>Informes de error</title> - <simpara> - Si cree que ha encontrado un error en el PHP, por favor infórmenos. - Los desarrolladores del PHP probablemente no tengan conocimiento - del mismo, y salvo si informa del mismo, pocas probabilidades habrá - de que lo solucionen. Puede informar de los errores usando el - sistema de rastreo de errores en <ulink - url="&url.php.bugs;">&url.php.bugs;</ulink>. - </simpara> - </sect2> - - <sect2> - <title>Otros problemas</title> - - <simpara> - Si aún se encuentra atascado, alguien de la lista de correos del - PHP puede ser capaz de ayudarle. Deberá buscar primero en los - archivos, por si acaso alguien ya ha respondido a otra persona - que tuvo el mismo problema que usted. Los archivos están disponibles - desde la página de soporte en <ulink - url="&url.php;">&url.php;</ulink>. Para suscribirse a la lista de - correo de PHP, envíe un correo vacío a <ulink - url="mailto:&email.php3.subscribe;">&email.php3.subscribe;</ulink>. - La dirección de la lista de correo es <literal>&email.php3;</literal>. - </simpara> - <simpara> - Si desea ayuda sobre la lista de correo, intente ser preciso y - de los detalles necesarios sobre su entorno (qué sistema operativo, - qué versión de PHP, qué servidor web, si está ejecutando el PHP - como CGI o como módulo de servidor, etc.) y también código - suficiente para que otros puedan reproducir y comprobar su - problema. - </simpara> - </sect2> - - </sect1> - - </chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> + <chapter id="installation"> + <title>Instalación</title> + + <sect1 id="downloading"> + <title>Bajándose la última versión</title> + <simpara> + El código fuente y las distribuciones binarias para algunas + plataformas (incluído Windows) se pueden encontrar en <literal><ulink + url="http://www.php.net/">http://www.php.net/</ulink></literal>. + </simpara> + </sect1> + + <sect1 id="install-unix"> + <title>Instalación en sistemas UNIX</title> + + <para> + Esta sección le guiará a través de la configuración e + instalación del PHP. Conocimientos y software necesarios: + + <itemizedlist> + <listitem> + <simpara> + Habilidades básicas en UNIX (ser capaz de manejar el "make" + y un compilador de C) + </simpara> + </listitem> + <listitem> + <simpara> + Un compilador ANSI de C + </simpara> + </listitem> + <listitem> + <simpara> + Un servidor web + </simpara> + </listitem> + </itemizedlist> + </para> + + <sect2> + <title> + Instrucciones Rápidas de Instalación (Versión Módulo de Apache) + </title> + + <para> + <informalexample> + <programlisting> +1. gunzip apache_1.3.x.tar.gz +2. tar xvf apache_1.3.x.tar +3. gunzip php-3.0.x.tar.gz +4. tar xvf php-3.0.x.tar +5. cd apache_1.3.x +6. ./configure --prefix=/www +7. cd ../php-3.0.x +8. ./configure --with-mysql --with-apache=../apache_1.3.x --enable-track-vars +9. make +10. make install +11. cd ../apache_1.3.x +12. ./configure --prefix=/www --activate-module=src/modules/php3/libphp3.a +13. make +14. make install + + En lugar de este paso quizás prefiera simplemente copiar el binario + httpd encima del binario existente. Si lo hace, asegúrese antes de + cerrar su servidor. + +15. cd ../php-3.0.x +16. cp php3.ini-dist /usr/local/lib/php3.ini + + Puede editar el archivo /usr/local/lib/php3.ini para ajustar opciones + del PHP. Si prefiere tenerlo en otro sitio, utilice + --with-config-file-path=/path en el paso 8. + +17. Edite su archivo httpd.conf o srm.conf y añada: + + AddType application/x-httpd-php3 .php3 + + Puede elegir la extensión que desee aquí. .php3 es simplemente nuestra + sugerencia. + +18. Utilice su método habitual para iniciar el servidor Apache (debe detener + y reiniciar el servidor, no solamente hacerlo recargarse usando una + señal HUP o USR1.) + </programlisting> + </informalexample> + </para> + + </sect2> + + <sect2> + <title>Configuración</title> + <para> + Hay dos maneras de configurar el PHP. + <itemizedlist> + <listitem> + <para> + Utilizando el script de "setup" que viene con el PHP. Este + script le hace una serie de preguntas (casi como el script + "install" del PHP/FI 2.0) y ejecuta el "configure" al final. + Para ejecutar este script, escriba <command>./setup</command>. + </para> + <para> + Este script también creará un archivo llamado "do-conf", que + contendrá las opciones pasadas a la configuración. Puede editar + este archivo para cambiar algunas opciones sin tener que + re-ejecutar el "setup". Escriba luego <command>./do-conf</command> + para ejecutar la configuración con las nuevas opciones. + </para> + </listitem> + <listitem> + <para> + Ejecutar el "configure" a mano. Para ver las opciones de que + dispone, escriba <command>./configure --help</command>. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Los detalles sobre las distintas opciones de configuración son + listados a continuación. + </para> + </sect2> + + <sect2 id="with-apache"> + <title>Módulo del Apache</title> + + <para> + Para configurar el PHP como módulo de Apache, responda "yes" a + "Build as an Apache module?" (la opción <option><link linkend="with-apache"> + --with-apache</link>=<replaceable>DIR</replaceable></option> + es la que lo configura) y especifique el directorio base de la + distribución de Apache. Si ha desempacado el Apache en + <filename + class="directory">/usr/local/www/apache_1.2.4</filename>, este será + su directorio base de la distribución de Apache. El directorio + por defecto es <filename + class="directory">/usr/local/etc/httpd</filename>. + </para> + </sect2> + + <sect2 id="with-fhttpd"> + <title>Módulo fhttpd</title> + + <para> + Para configurar el PHP como módulo fhttpd, responda "yes" a + "Build as an fhttpd module?" (la opción <option><link linkend="with-fhttpd"> + --with-fhttpd</link>=<replaceable>DIR</replaceable></option> + es la que lo configura) y especifique el directorio base + del fuente del fhttpd. El directorio por defecto es <filename + class="directory">/usr/local/src/fhttpd</filename>. Si está + ejecutando fhttpd, configurar PHP como módulo le dará mejor + rendimiento, más control y capacidad de ejecución remota. + </para> + </sect2> + + <sect2 id="install-cgi"> + <title>CGI version</title> + <para> + El valor por defecto es configurar el PHP como programa CGI. + Si está ejecutando un servidor web para el que el PHP tiene + soporte como módulo, debería elegir dicha solución por motivos + de rendimiento. Sin embargo, la versión CGI permite a los + usuarios del Apache el ejecutar distintas páginas con PHP bajo + distintos identificadores de usuario. Por favor, asegúrese + de haber leído el <link linkend="security">capítulo sobre + Seguridad</link> si va a ejecutar el PHP como CGI. + </para> + </sect2> + + <sect2> + <title>Opciones de soporte para Base de Datos</title> + <para> + El PHP tiene soporte nativo para bastantes bases de datos + (así como para ODBC): + </para> + + <sect3 id="with-adabas"> + <title>Adabas D</title> + <synopsis> + <option>--with-adabas<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Compila con soporte para Adabas D. El parámetro es el directorio + de instalación de Adabas D y por defecto vale <filename + class="directory">/usr/local/adabasd</filename>. + </simpara> + <simpara> + <ulink url="http://www.adabas.com/">Página de Adabas</ulink> + </simpara> + </sect3> + + <sect3 id="with-dbase"> + <title>dBase</title> + <synopsis> + <option>--with-dbase</option> + </synopsis> + <simpara> + Habilita el soporte integrado para DBase. No se precisan librerías + externas. + </simpara> + </sect3> + + <sect3 id="with-filepro"> + <title>filePro</title> + <synopsis> + <option>--with-filepro</option> + </synopsis> + <simpara> + Habilita el soporte integrado de sólo lectura para filePro. No se + precisan librerías externas. + </simpara> + </sect3> + + <sect3 id="with-msql"> + <title>mSQL</title> + <synopsis> + <option>--with-msql<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Habilita el soporte para mSQL. El parámetro es el directorio + de instalación de mSQL y por defecto vale <filename + class="directory">/usr/local/Hughes</filename>. Este es el + directorio por defecto de la distribución mSQL 2.0. + <command>configure</command> detecta automáticamente qué versión + de mSQL está ejecutándose y el PHP soporta tanto 1.0 como 2.0, pero + si compila el PHP con mSQL 1.0 sólo podrá acceder a bases de datos + de esa versión y viceversa. + </simpara> + <simpara> + Vea también Directivas de <link linkend="ini.sect.msql">Configuración + de mSQL</link> en el <link linkend="configuration.file">archivo de + configuración</link>. + </simpara> + <simpara> + <ulink url="http://www.hughes.com.au">Página de mSQL</ulink> + </simpara> + </sect3> + + <sect3 id="with-mysql"> + <title>MySQL</title> + <synopsis> + <option>--with-mysql<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Habilita el soporte para MySQL. El parámetro es el directorio + de instalación de MySQL y por defecto vale <filename + class="directory">/usr/local</filename>. Este es el directorio + de instalación de la distribución de MySQL. + </simpara> + <simpara> + Vea también Directivas de <link linkend="ini.sect.mysql">Configuración + de MySQL</link> en el <link linkend="configuration.file">archivo de + configuración</link>. + </simpara> + <simpara> + <ulink url="http://www.tcx.se">Página de MySQL</ulink> + </simpara> + </sect3> + + <sect3 id="with-iodbc"> + <title>iODBC</title> + <synopsis> + <option>--with-iodbc<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para iODBC. Esta característica se desarrolló + inicialmente para el iODBC Driver Manager, un gestor de controlador + de ODBC de redistribución libre que ese ejecuta bajo varios + sabores de UNIX. El parámetro es el directorio de instalación + de iODBC y por defecto vale <filename class="directory">/usr/local</filename>. + </simpara> + <simpara> + <ulink url="http://users.ids.net/~bjepson/freeODBC/">Página de + FreeODBC</ulink> o <ulink url="http://www.iodbc.org">página de + iODBC</ulink> + </simpara> + </sect3> + + <sect3 id="with-openlink"> + <title>OpenLink ODBC</title> + <synopsis> + <option>--with-openlink<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para OpenLink ODBC. El parámetro es el directorio + de instalación de OpenLink ODBC y por defecto vale + <filename class="directory">/usr/local/openlink</filename>. + </simpara> + <simpara> + <ulink url="http://www.openlinksw.com/">Página de OpenLink Software</ulink> + </simpara> + </sect3> + + <sect3 id="with-oracle"> + <title>Oracle</title> + <synopsis> + <option>--with-oracle<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para Oracle. Se ha probado y debería funcionar al + menos con las versiones de la 7.0 a la 7.3. El parámetro es el + directorio <envar>ORACLE_HOME</envar>. No necesita especificar + este parámetro si su entorno de Oracle ya está ajustado.</simpara> + <simpara> + <ulink url="http://www.oracle.com">Página de Oracle</ulink> + </simpara> + </sect3> + + <sect3 id="with-pgsql"> + <title>PostgreSQL</title> + <synopsis> + <option>--with-pgsql<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para PostgreSQL. El parámetro es el directorio + base de la instalación de PostgreSQL y por defecto vale <filename + class="directory">/usr/local/pgsql</filename>. + </simpara> + <simpara> + Vea también Directivas de <link linkend="ini.sect.pgsql">Configuración + de Postgres</link> en el <link + linkend="configuration.file">archivo de configuración</link>. + </simpara> + <simpara> + <ulink url="http://www.postgreSQL.org/">Página de PostgreSQL</ulink> + </simpara> + </sect3> + + <sect3 id="with-solid"> + <title>Solid</title> + <synopsis> + <option>--with-solid<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para Solid. El parámetro es el directorio de + instalación y vale por defecto <filename + class="directory">/usr/local/solid</filename>. + </simpara> + <simpara> + <ulink url="http://www.solidtech.com">Página de Solid</ulink> + </simpara> + </sect3> + + <sect3 id="with-sybase"> + <title>Sybase</title> + <synopsis> + <option>--with-sybase<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para Sybase. El parámetro es el directorio de + instalación y vale por defecto <filename + class="directory">/home/sybase</filename>. + </simpara> + <simpara> + Vea también Directivas de <link linkend="ini.sect.sybase">Configuración + de Sybase</link> en el <link + linkend="configuration.file">archivo de configuración</link>. + </simpara> + <simpara> + <ulink url="http://www.sybase.com">Página de Sybase</ulink> + </simpara> + </sect3> + + <sect3 id="with-sybase-ct"> + <title>Sybase-CT</title> + <synopsis> + <option>--with-sybase-ct<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para Sybase-CT. El parámetro es el directorio + de instalación de Sybase-CT y por defecto vale <filename + class="directory">/home/sybase</filename>. + </simpara> + <simpara> + Vea también Directovas de <link linkend="ini.sect.sybct">Configuración + de Sybase-CT</link> en el <link + linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="with-velocis"> + <title>Velocis</title> + <synopsis> + <option>--with-velocis<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para Velocis. El parámetro es el directorio de + instalación de Velocis y vale por defecto <filename + class="directory">/usr/local/velocis</filename>. + </simpara> + <simpara> + <ulink url="http://www.raima.com">Página de Velocis</ulink> + </simpara> + </sect3> + + <sect3 id="with-custom-odbc"> + <title>Una librería a medida de ODBC</title> + <synopsis> + <option>--with-custom-odbc<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para una librería a medida arbitraria de ODBC. + El parámetro es el directorio base y por defecto vale <filename + class="directory">/usr/local</filename>. + </simpara> + <simpara> + Esta opción implica que se ha definido CUSTOM_ODBC_LIBS cuando se + ejecutó el script de configuración. También deberá tener una + cabecera odbc.h válida en algún lugar de su sendero (path) de + inclusión. Si no tiene uno, créelo e incluya su cabecera específica + desde ahí. Su cabecera puede requerir algunas definiciones extra, + particularmente si es multiplataforma. Defínalas en CFLAGS.</simpara> + <simpara> + Por ejemplo, puede usar Sybase SQL Anywhere bajo QNX como + sigue: + <literal> + CFLAGS=-DODBC_QNX LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib + -lodbc" ./configure --with-custom-odbc=/usr/lib/sqlany50 + </literal> + </simpara> + </sect3> + + <sect3 id="disable-unified-odbc"> + <title>ODBC Unificado</title> + <synopsis> + <option>--disable-unified-odbc</option> + </synopsis> + <simpara> + Deshabilita el módulo de ODBC Unificado, que es un interfaz común + a todas las bases de datos con interfaces basados en ODBC, tales + como Solid y Adabas D. También funciona para librerías normales + de ODBC. Ha sido probado con iODBC, Solid, Adabas D y Sybase SQL + Anywhere. Requiere que uno (y sólo uno) de estos módulos o el + módulo de Velocis esté habilitado, o que se especifique una librería + a medida de ODBC. Esta opción sólo se puede aplicar si alguna de + estas opciones es usada: <link + linkend="with-iodbc">--with-iodbc</link>, <link + linkend="with-solid">--with-solid</link>, <link + linkend="with-adabas">--with-adabas</link>, <link + linkend="with-velocis">--with-velocis</link>, o <link + linkend="with-adabas">--with-custom-odbc</link>. + </simpara> + <simpara> + Vea también Directivas de <link linkend="ini.sect.uodbc">Configuración + de ODBC Unificado</link> en el <link + linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="with-ldap"> + <title>LDAP</title> + <synopsis> + <option>--with-ldap<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Incluye soporte para <acronym>LDAP</acronym> (Lightweight + Directory Access Protocol - Protocolo Ligero de Acceso a + Directorios). El parámetro es el directorio base de instalación + de LDAP, y por defecto vale <filename + class="directory">/usr/local/ldap</filename>. + </simpara> + <simpara> + Puede encontrar más información sobre LDAP en <ulink + url="ftp://ftp.isi.edu/in-notes/rfc1777.txt">RFC1777</ulink> y en + <ulink + url="ftp://ftp.isi.edu/in-notes/rfc1778.txt">RFC1778</ulink>. + </simpara> + </sect3> + + </sect2> + + <sect2> + <title>Otras opciones de configuración</title> + + <sect3 id="with-mcrypt"> + <title>--with-mcrypt<replaceable>=DIR</replaceable></title> + <synopsis> + <option>--with-mcrypt</option> + </synopsis> + <simpara> + Incluye soporte para la librería mcrypt. Vea la <link + linkend="ref.mcrypt">documentación de mcrypt</link> para + más información. Si utiliza el argumento opcional + <replaceable>DIR</replaceable>, el PHP buscará mcrypt.h + en <replaceable>DIR</replaceable>/include. + </simpara> + </sect3> + + <sect3 id="enable-sysvsem"> + <title>--enable-sysvsem</title> + <synopsis> + <option>--enable-sysvsem</option> + </synopsis> + <simpara> + Incluye soporte para semáforos Sys V (soportados por muchos + derivados Unix). Vea la <link linkend="ref.sem">documentación + sobre Semáforos y Memoria Compartida</link> para más información. + </simpara> + </sect3> + + <sect3 id="enable-sysvshm"> + <title>--enable-sysvshm</title> + <synopsis> + <option>--enable-sysvshm</option> + </synopsis> + <simpara> + Incluye soporte para la memoria compartida Sys V (soportada por + muchos derivados Unix). Vea la <link linkend="ref.sem">documentación + sobre Semáforos y Memoria Compartida</link> para más información. + </simpara> + </sect3> + + <sect3 id="with-xml"> + <title>--with-xml</title> + <synopsis> + <option>--with-xml</option> + </synopsis> + <simpara> + Incluye soporte para un parser XML no validador que utiliza + la <ulink url="&url.expat;">librería expat</ulink> de James Clark. + Vea la <link linkend="ref.xml">referencia de funciones XML</link> + para más detalles. + </simpara> + </sect3> + + <sect3 id="enable-maintainer-mode"> + <title>--enable-maintainer-mode</title> + <synopsis> + <option>--enable-maintainer-mode</option> + </synopsis> + <simpara> + Activa avisos extra de dependencias y del compilador utilizados + por algunos de los desarrolladores del PHP.</simpara> + </sect3> + + <sect3 id="with-system-regex"> + <title>--with-system-regex</title> + <synopsis> + <option>--with-system-regex</option> + </synopsis> + <simpara> + Utiliza la librería de expresiones regulares del sistema en + lugar de la incluída. Si está compilando PHP como módulo de + servidor, debe utilizar la misma librería cuando genere el + PHP y cuando lo enlace con el servidor. Active esto si la + librería del sistema proporciona características especiales + que pueda necesitar. Se recomienda utilizar la librería + incluída siempre que sea posible.</simpara> + </sect3> + + <sect3 id="with-config-file-path"> + <title>--with-config-file-path</title> + <synopsis> + <option>--with-config-file-path=DIR</option> + </synopsis> + <simpara> + El path utilizado para buscar <link linkend="configuration.file">el + archivo de configuración</link> cuando arranca el PHP. + </simpara> + </sect3> + + <sect3 id="with-exec-dir"> + <title>--with-exec-dir</title> + <synopsis> + <option>--with-exec-dir<replaceable>=DIR</replaceable></option> + </synopsis> + <simpara> + Sólo permite ejecutar programas en DIR cuando está en modo + seguro. Por defecto vale <filename class="directory">/usr/local/bin</filename>. + Esta opción sólo fija el valor por defecto. Puede ser cambiado + posteriormente mediante la directiva + <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link> + en el <link linkend="configuration.file">fichero de configuración + </link>. + </simpara> + </sect3> + + <sect3 id="enable-debug"> + <title>--enable-debug</title> + <synopsis> + <option>--enable-debug</option> + </synopsis> + <simpara> + Habilita información de depuración adicional. Esto hace posible + obtener información más detallada cuando hay problemas con el PHP. + (Nótese que esto no tiene que ver con las facilidades de depuración + o con la información disponible para los script PHP). + </simpara> + </sect3> + + <sect3 id="enable-safe-mode"> + <title>--enable-safe-mode</title> + <synopsis> + <option>--enable-safe-mode</option> + </synopsis> + <simpara> + Habilita el "modo seguro" por defecto. Esto impone varias + restricciones sobre lo que el PHP puede hacer, tales como + abrir fichero sólo en el raiz de documentos. Lea el <link + linkend="security">capítulo de Seguridad</link> para más + información. Los usuarios de CGI deberán siempre habilitar + el modo seguro. Esta opción sólo fija el valor por defecto. + Puede ser habilitado o deshabilitado posteriormente mediante + la directiva <link linkend="ini.safe-mode">safe_mode</link> en + el <link linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="enable-track-vars"> + <title>--enable-track-vars</title> + <synopsis> + <option>--enable-track-vars</option> + </synopsis> + <simpara> + Hace que el PHP lleve el control de dónde proceden las variables + GET/POST/cookie usando las matrices HTTP_GET_VARS, HTTP_POST_VARS + y HTTP_COOKIE_VARS. Esta opción sólo fija el valor por defecto. + Puede ser habilitado o deshabilitado posteriormente mediante la + directiva <link + linkend="ini.track-vars">track_vars</link> en el + <link linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="enable-magic-quotes"> + <title>--enable-magic-quotes</title> + <synopsis> + <option>--enable-magic-quotes</option> + </synopsis> + <simpara> + Habilita las comillas mágicas por defecto. Esta opción sólo + fija el valor por defecto. Puede ser habilitada o deshabilitada + posteriormente mediante la directiva <link + linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link> + en el <link + linkend="configuration.file">archivo de configuración</link>. + Vea también las directivas <link linkend="ini.magic-quotes-gpc"> + magic_quotes_gpc</link> y <link + linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>. + </simpara> + </sect3> + + <sect3 id="enable-debugger"> + <title>--enable-debugger</title> + <synopsis> + <option>--enable-debugger</option> + </synopsis> + <simpara> + Habilita el soporte de depuración interno del PHP. Esta + característica aún está en estado experimental. Vea también + las directivas de <link linkend="ini.sect.debugger">Configuración + del Depurador</link> en el <link + linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="enable-discard-path"> + <title>--enable-discard-path</title> + <synopsis> + <option>--enable-discard-path</option> + </synopsis> + <simpara> + Si está habilitado, el ejecutable CGI del PHP se puede situar + tranquilamente fuera del árbol de la web y la gente no podrá + saltarse la seguridad del .htaccess. Lea la <link + linkend="security.cgi.shell">sección en el capítulo de + seguridad</link> sobre esta opción. + </simpara> + </sect3> + + <sect3 id="enable-bcmath"> + <title>--enable-bcmath</title> + <synopsis> + <option>--enable-bcmath</option> + </synopsis> + <simpara> + Habilita las funciones matemáticas de precisión arbitraria + estilo <command>bc</command>. Vea también la opción <link + linkend="ini.sect.bcmath">bcmath.scale </link> en el + <link linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="enable-force-cgi-redirect"> + <title>--enable-force-cgi-redirect</title> + <synopsis> + <option>--enable-force-cgi-redirect</option> + </synopsis> + <simpara> + Habilita la comprobación de seguridad para redirecciones internas + del servidor. Deberá usar esta opción si está ejecutando la + versión CGI bajo Apache. + </simpara> + <simpara> + Cuando se utiliza el PHP como un ejecutable CGI, siempre + comprueba primero is está siendo utilizado bajo redirección + (por ejemplo bajo Apache, usando directivas Action). Esto + asegura que el ejecutable del PHP no se puede usar para saltarse + los mecanismos estánder de autentificación del servidor web + llamando al ejecutale directamente, como en <filename + role="url">http://my.host/cgi-bin/php/secret/doc.html</filename>. + Este ejemplo accede al archivo <filename + role="url">http://my.host/secret/doc.html</filename> pero sin + respetar ningún ajuste de seguridad del httpd para el directorio + <filename role="dir">/secret</filename>. + </simpara> + <simpara> + No habilitando esta opción se deshabilita la comprobación y + se permite el saltarse los ajustes de seguridad y autenticación + del httpd. Haga esto sólo si el software de su servidor no + puede indicar que se ha realizado una redirección segura y + que todos sus archivos bajo la raiz de documentos y los + directorios de los usuarios pueden ser accedidos por cualquiera. + </simpara> + <simpara> + Lea la <link linkend="security.cgi.force-redirect">sección en + el capítulo de seguridad</link> acerca de esta opción. + </simpara> + </sect3> + + <sect3 id="disable-short-tags"> + <title>--disable-short-tags</title> + <synopsis> + <option>--disable-short-tags</option> + </synopsis> + <simpara> + Deshabilita las etiquetas de PHP en formato corto <literal>&lt;? ?&gt;</literal>. + Debe deshabilitar el formato corto si desea usar PHP con + <acronym>XML</acronym>. Con el formato corto deshabilitado, la + única etiqueta de código de PHP es <literal>&lt;?php ?&gt;</literal>. + Esta opción sólo fija el valor por defecto. Puede ser habilitada o + deshabilitada posteriormente mediante la directiva <link + linkend="ini.short-open-tag">short_open_tag</link> en el <link + linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="enable-url-includes"> + <title>--enable-url-includes</title> + <synopsis> + <option>--enable-url-includes</option> + </synopsis> + <simpara> + Hace posible ejecutar código en otros servidores HTTP o FTP + directamente desde el PHP usando <link + linkend="function.include">include()</link>. Vea también la + opción <link + linkend="ini.include-path">include_path</link> en el + <link linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect3> + + <sect3 id="disable-syntax-hl"> + <title>--disable-syntax-hl</title> + <synopsis> + <option>--disable-syntax-hl</option> + </synopsis> + <simpara> + Desconecta el resalte de sintáxis. + </simpara> + </sect3> + + <sect3> + <title>CPPFLAGS y LDFLAGS</title> + <para> + Para hacer que la instalación de PHP busque los archivos de cabecera + o de librería en distintos directorios, modifique las variables de + entorno <envar>CPPFLAGS</envar> y <envar>LDFLAGS</envar> respectivamente. + Si está utilizando un shell "sensible", podrá ejecutar + <command> + LDFLAGS=-L/my/lib/dir CPPFLAGS=-I/my/include/dir ./configure + </command> + </para> + </sect3> + + </sect2> + + <sect2> + <title>Construyendo</title> + <simpara> + Cuando el PHP está configurado, ya está listo para construir el + ejecutable CGI o la librería PERL. El comando <command>make</command> + debería ocuparse de esto. Si fallara y no puede saber el motivo, vea + la <link linkend="install-problems">sección de Problemas</link>. + </simpara> + </sect2> + + <sect2> + <title>Probando</title> + <simpara> + Si ha construído el PHP como un programa CGI, puede probar su + funcionamiento tecleando <command>make test</command>. Siempre es + buena idea probar su construcción. Así puede atrapar pronto + los problemas del PHP en su plataforma sin tener que batallar + con ellos luego. + </simpara> + </sect2> + + <sect2> + <title>Comprobando la velocidad</title> + <simpara> + Si ha construído el PHP como un programa CGI, puede comprobar + la velocidad de su código escribiendo <command>make bench</command>. + Nótese que se el modo seguro está habilitado por defecto, el test + no podrá finalizar si se toma más de los 30 segundos disponibles. + Esto se debe a que la función <function>set_time_limit</function> + no se puede usar en modo seguro. Use el ajuste de configuración <link + linkend="ini.max-execution-time">max_execution_time</link> + para controlar este tiempo en sus propios script. + <command>make bench</command> ignora el <link + linkend="configuration.file">archivo de configuración</link>. + </simpara> + </sect2> + + </sect1> + + <sect1 id="install-windows95-nt"> + <title>Instalación en sistemas Windows 95/98/NT</title> + + <simpara> + Esta guía de instalación le ayudará a instalar y configurar el PHP + en sus servidores web bajo Windows 9x/NT. Esta guía fue compilada + por &link.bob;. La última revisión puede encontrarse en <ulink + url="&url.win32install">&url.win32install</ulink>. + </simpara> + <para> + Esta guía proporciona soporte de instalacion para: + <itemizedlist> + <listitem> + <para> + Personal Web Server (se recomienda la última versión) + </para> + </listitem> + <listitem> + <para> + Internet Information Server 3 ó 4 + </para> + </listitem> + <listitem> + <para> + Apache 1.3.x + </para> + </listitem> + <listitem> + <para> + Omni HTTPd 2.0b1 + </para> + </listitem> + </itemizedlist> + </para> + + <sect2> + <title>Pasos Generales de Instalación</title> + + <para> + Los siguientes pasos deben realizarse en todas las instalaciones + antes de las instrucciones específicas de cada servidor. + + <itemizedlist> + <listitem> + <para> + Extraiga el archivo de distribución a un directorio de su + elección. "C:\PHP3\" es un buen comienzo. + </para> + </listitem> + <listitem> + <para> + Copie el archivo 'php3.ini-dist' a su directorio '%WINDOWS%' + y renómbrelo a 'php3.ini'. Su directorio '%WINDOWS%' es + típicamente: + <simplelist> + <member>c:\windows para Windows 95/98</member> + <member>c:\winnt o c:\winnt40 para servidores NT</member> + </simplelist> + </para> + </listitem> + <listitem> + <para> + Edite su archivo 'php3.ini': + <itemizedlist> + <listitem> + <simpara> + Necesitaá cambiar la opción 'extension_dir' para que apunte + a su php-install-dir, o a donde quiera que haya puesto + sus archivos 'php3_*.dll'. P.ej.: c:\php3 + </simpara> + </listitem> + <listitem> + <simpara> + Si está utilizando Omni Httpd, no siga el siguiente paso. + Fije el 'doc_root' para que apunte a la raiz web de sus + servidores. P.ej.: c:\apache\htdocs o c:\webroot + </simpara> + </listitem> + <listitem> + <simpara> + Elija qué módulos desearía cargar cuando comience el PHP. + Puede descomentar las líneas: 'extension=php3_*.dll' para + cargar estos módulos. Algunos módulos requieren que tenga + instaladas en sus sistema librerías adicionales para que + el módulo funcione correctamente. El <ulink + url="&url.php.faq">FAQ</ulink> de PHP tiene más información + sobre dónde obtener librerías de soporte. También puede + cargar un módulo dinámicamente en su script utilizando: + <command>dl("php_*.dll");</command> + </simpara> + </listitem> + <listitem> + <simpara> + En el PWS y el IIS puede fijar el browscap.ini para que apunte + a: 'c:\windows\system\inetsrv\browscap.ini' bajo Windows 95/98 + y a 'c:\winnt\system32\inetsrv\browscap.ini' bajo NT + Server. Se puede encontrar información adicional sobre el uso + de la funcionalidad del browscap en el PHP en este <ulink + url="&url.browscap;">servidor alternativo</ulink>. Elija el + botón "fuente" para verlo en acción. + </simpara> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist></para> + <simpara> + Las DLL para las extensiones del PHP van precedidas de 'php3_'. + Esto evita confusiones entre las extensiones del PHP y sus + librerías de soporte. + </simpara> + + </sect2> + + <sect2> + <title>Windows 95/98/NT y PWS/IIS 3</title> + + <simpara> + El método recomendado para configurar estos servidores es usar + el archivo INF incluído con la distribución (php_iis_reg.inf). + Quizás desee editar este archivo y asegurarse que las extensiones + y directorios de instalación se ajustan a su configuración. O puede + seguir los pasos que siguen para hacerlo de forma manual. + </simpara> + <simpara> + AVISO: Estos pasos conllevan el trabajar directamente con el + registro de windows. Un error aquí puede dejar su sistema en + un estado inestable. Le recomendamos encarecidamente que haga + una copia de seguridad del registro con antelación. El equipo + de Desarrollo del PHP no se hará responsable si se daña su + registro. + </simpara> + + <para> + <itemizedlist> + <listitem> + <simpara> + Ejecute Regedit. + </simpara> + </listitem> + <listitem> + <simpara> + Navegue hasta: <literal>HKEY_LOCAL_MACHINE /System + /CurrentControlSet /Services /W3Svc /Parameters + /ScriptMap</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + En el menú de edición elija: <literal>New->String Value</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Escriba la extensión que desea usar para sus script + PHP. P.ej.: <literal>.php3</literal> + </simpara> + </listitem> + <listitem> + <simpara> + Haga doble click en el nuevo valor de cadena y escriba la + ruta al <literal>php.exe</literal> en el campo del valor. + P.ej.: <literal>c:\php3\php.exe %s %s</literal>. La parte '%s %s' + son MUY importantes, pues el PHP no funcionará correctamente + sin ella. + </simpara> + </listitem> + <listitem> + <simpara> + Repita estos pasos para cada extensión que desee asociar con + los scripts PHP. + </simpara> + </listitem> + <listitem> + <simpara> + Ahora navegue hasta: <literal>HKEY_CLASSES_ROOT</literal> + </simpara> + </listitem> + <listitem> + <simpara> + En el menú de edición elija: <literal>New->Key</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Déle a la clave el nombre de la extensión que preparó + en la sección anterior. P.ej.: <literal>.php3</literal> + </simpara> + </listitem> + <listitem> + <simpara> + Marque la nueva clave y en el panel del lado derecho haga + doble click en "default value" y escriba <literal>phpfile</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Repita el último paso para cada extensión que haya preparado + en la sección previa. + </simpara> + </listitem> + <listitem> + <simpara> + Ahora cree otra <literal>New->Key</literal> bajo + <literal>HKEY_CLASSES_ROOT</literal> y denomínela + <literal>phpfile</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Marque la nueva clave <literal>phpfile</literal> y haga doble + click en el panel derecho sobre "default value" y escriba + <literal>PHP Script</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Pulse el botón derecho sobre la clave <literal>phpfile</literal> + y seleccione <literal>New->Key</literal> y llámela <literal>Shell</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Pulse el botón derecho sobre la clave <literal>Shell</literal> + y elija <literal>New->Key</literal> y llámela <literal>open</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Pulse el botón derecho sobre la clave <literal>open</literal> + y elija <literal>New->Key</literal> y llámela + <literal>command</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Marque la nueva clave <literal>command</literal> y en el panel + derecho haga doble click sobre "default value" y entre la ruta + hasta el <literal>php.exe</literal>. P.ej.: + <literal>c:\php3\php.exe -q %1</literal>. (no olvide el + <literal>%1</literal>). + </simpara> + </listitem> + <listitem> + <simpara> + Salga del Regedit. + </simpara> + </listitem> + </itemizedlist> + </para> + <simpara> + Los usuarios de PWS e IIS3 tienen ahora un sistema completamente + operativo. Los usuarios del IIS3 también pueden usar una curiosa + <ulink url="http://www.genusa.com/iis/iiscfg.html">herramienta</ulink> + de Steven Genusa para configurar sus mapeados de script. + </simpara> + + </sect2> + + <sect2> + <title>Windows NT e IIS 4</title> + + <simpara> + Para instalar el PHP en un NT Server con IIS 4, siga estas + instrucciones: + </simpara> + + <para> + <itemizedlist> + <listitem> + <simpara> + En el Controlador de Servicios de Internet (MMC), elija el sitio + Web o el directorio de comienzo de una aplicación. + </simpara> + </listitem> + <listitem> + <simpara> + Abra las propiedades del directorio (haciendo click derecho y + eligiendo propiedades) y luego pulse sobre la pestaña Carpeta + Inicial, Directorio Virtual o Directorio. + </simpara> + </listitem> + <listitem> + <simpara> + Pulse el botón Configuración y luego pulse sobre la pestaña + Mapas de Aplicación. + </simpara> + </listitem> + <listitem> + <simpara> + Pulse en Añadir, y en la caja Programa, escriba: + <literal>c:\path-to-php-dir\php.exe %s %s</literal>. DEBE + mantene los %s %s al final, pues el PHP no funcionará + correctamente si se equivoca al hacerlo. + </simpara> + </listitem> + <listitem> + <simpara> + En la caja Extensión, escriba la extensión de fichero que desea + asociar a los script de PHP. Debe repetir los pasos 5 y 6 para + cada extensión que desee asociar con los scripts PHP ( + <literal>.php3</literal> y <literal>.phtml</literal> son + habituales). + </simpara> + </listitem> + <listitem> + <simpara> + Ajuste la seguridad apropiada (esto se realiza en el Controlador + de Servicio de Internet (ISM)), y si su NT Server usa el sistema + de archivos NTFS, añada derechos de ejecución para I_USR_ al + directorio que contenga el <literal>php.exe</literal>. + </simpara> + </listitem> + </itemizedlist> + </para> + + </sect2> + + <sect2> + <title>Windows 9x/NT y Apache 1.3.x</title> + + <simpara> + Debe editar sus archivos <literal>srm.conf</literal> o + <literal>httpd.conf</literal> para configurar el Apache + para que trabaje con el ejecutable CGI del PHP. + </simpara> + <simpara> + Aunque puede haber algunas variaciones al configurar PHP bajo + Apache, esta es lo suficientemente simple para ser usada por + el novato. Por favor, consulte la Documentación del Apache para + saber de las subsiguientes directivas de configuración. + </simpara> + + <para> + <itemizedlist> + <listitem> + <simpara> + <literal> + ScriptAlias /php3/ "c:/ruta-al-dir-del-php/" + </literal> + </simpara> + </listitem> + <listitem> + <simpara> + <literal> + AddType application/x-httpd-php3 .php3 + </literal> + </simpara> + </listitem> + <listitem> + <simpara> + <literal> + AddType application/x-httpd-php3 .phtml + </literal> + </simpara> + </listitem> + <listitem> + <simpara> + <literal> + Action application/x-httpd-php3 "/php3/php.exe" + </literal> + </simpara> + </listitem> + </itemizedlist> + </para> + + <simpara> + Para utilizar la capacidad de marcado del código fuente, cree + simplemente un script de PHP y pegue este código en él: + <literal>&lt;?php show_source("script_original_php.php3"); ?></literal>. + Sustituya <literal>script_original_php.php3</literal> por el nombre + del archivo del que desea visualizar el código fuente (esta es la + única forma de hacerlo). + <emphasis>Nota:</emphasis> Bajo Win-Apache todas las barras + invertidas de una ruta tal como: "c:\directory\file.ext", + deben ser convertidas a barras hacia adelante. + </simpara> + + </sect2> + + <sect2> + <title>Omni HTTPd 2.0b1 para Windows</title> + + <simpara> + Esta ha resultado ser la configuración más sencilla: + </simpara> + + <para> + <simplelist> + <member> + Paso 1: Instale el servidor Omni + </member> + <member> + Paso 2: Pulse el botón derecho sobre el icono azul + del OmniHTTPd que está en la barrita del sistema y elija + <literal>Propiedades</literal> + </member> + <member> + Paso 3: Pulse sobre <literal>Web Server Global + Settings</literal> + </member> + <member> + Paso 4: En la pestaña 'External', escriba: <literal>virtual = .php3 + | actual = c:\ruta-al-dir-del-php\php.exe</literal> + </member> + <member> + Paso 5: En la pestaña <literal>Mime</literal>, escriba: + <literal>virtual = wwwserver/stdcgi | actual = .php3</literal> + </member> + <member> + Paso 6: Pulse en <literal>OK</literal> + </member> + </simplelist> + </para> + + <simpara> + Repita los pasos 2 a 6 para cada extensión que desee asociar + al PHP. + </simpara> + + </sect2> + + <sect2> + <title>Módulos del PHP</title> + + <para> + <table> + <title>Módulos del PHP</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>php3_calendar.dll</entry> + <entry>Funciones de conversión de calendario</entry> + </row> + <row> + <entry>php3_crypt.dll</entry> + <entry>Funciones de criptografía</entry> + </row> + <row> + <entry>php3_dbase.dll</entry> + <entry>Funciones para DBase</entry> + </row> + <row> + <entry>php3_dbm.dll</entry> + <entry>Emulación GDBM con la librería Berkeley DB2</entry> + </row> + <row> + <entry>php3_filepro.dll</entry> + <entry>Acceso SÓLO LECTURA a bases de datos filepro</entry> + </row> + <row> + <entry>php3_gd.dll</entry> + <entry>Funciones de librería GD para manipular GIF</entry> + </row> + <row> + <entry>php3_hyperwave.dll</entry> + <entry>Funciones de HyperWave</entry> + </row> + <row> + <entry>php3_imap4r2.dll</entry> + <entry>Funciones de IMAP 4</entry> + </row> + <row> + <entry>php3_ldap.dll</entry> + <entry>Funciones de LDAP</entry> + </row> + <row> + <entry>php3_msql1.dll</entry> + <entry>Cliente de mSQL 1</entry> + </row> + <row> + <entry>php3_msql2.dll</entry> + <entry>Cliente de mSQL 2</entry> + </row> + <row> + <entry>php3_mssql.dll</entry> + <entry>Cliente de MSSQL client (requiere las librerías de MSSQL DB</entry> + </row> + <row> + <entry>php3_mysql.dll</entry> + <entry>Funciones de MySQL</entry> + </row> + <row> + <entry>php3_nsmail.dll</entry> + <entry>Funciones de correo de Netscape</entry> + </row> + <row> + <entry>php3_oci73.dll</entry> + <entry>Funciones de Oracle</entry> + </row> + <row> + <entry>php3_snmp.dll</entry> + <entry>Funciones get y walk de SNMP (¡sólo en NT!)</entry> + </row> + <row> + <entry>php3_zlib.dll</entry> + <entry>Funciones de ZLib</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + </sect2> + + </sect1> + + <sect1 id="install-problems"> + <title>¿Problemas?</title> + + <sect2> + <title>Lea las PMF (FAQ)</title> + <simpara> + Algunos problemas son más comunes que otros. Los más comunes están + listados en las PMF (Preguntas Más Frecuentes) del PHP, que están + en <ulink url="&url.php.faq;">&url.php.faq;</ulink> + </simpara> + </sect2> + + <sect2> + <title>Informes de error</title> + <simpara> + Si cree que ha encontrado un error en el PHP, por favor infórmenos. + Los desarrolladores del PHP probablemente no tengan conocimiento + del mismo, y salvo si informa del mismo, pocas probabilidades habrá + de que lo solucionen. Puede informar de los errores usando el + sistema de rastreo de errores en <ulink + url="&url.php.bugs;">&url.php.bugs;</ulink>. + </simpara> + </sect2> + + <sect2> + <title>Otros problemas</title> + + <simpara> + Si aún se encuentra atascado, alguien de la lista de correos del + PHP puede ser capaz de ayudarle. Deberá buscar primero en los + archivos, por si acaso alguien ya ha respondido a otra persona + que tuvo el mismo problema que usted. Los archivos están disponibles + desde la página de soporte en <ulink + url="&url.php;">&url.php;</ulink>. Para suscribirse a la lista de + correo de PHP, envíe un correo vacío a <ulink + url="mailto:&email.php3.subscribe;">&email.php3.subscribe;</ulink>. + La dirección de la lista de correo es <literal>&email.php3;</literal>. + </simpara> + <simpara> + Si desea ayuda sobre la lista de correo, intente ser preciso y + de los detalles necesarios sobre su entorno (qué sistema operativo, + qué versión de PHP, qué servidor web, si está ejecutando el PHP + como CGI o como módulo de servidor, etc.) y también código + suficiente para que otros puedan reproducir y comprobar su + problema. + </simpara> + </sect2> + + </sect1> + + </chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/es/functions/strings.xml diff -u phpdoc/es/functions/strings.xml:1.6 phpdoc/es/functions/strings.xml:1.7 --- phpdoc/es/functions/strings.xml:1.6 Sat Jul 7 18:20:17 2001 +++ phpdoc/es/functions/strings.xml Sat Jul 7 19:11:25 2001 @@ -1,2971 +1,2971 @@ -<reference id="ref.strings"> - <title>Funciones de cadenas</title> - <titleabbrev>Cadenas</titleabbrev> - - <partintro> - <simpara> - Todas estas funciones manipulan cadenas de varias maneras. En las - secciones sobre expresiones regulares y manejo de URL se pueden - encontrar secciones más especializadas. - </simpara> - </partintro> - - <refentry id="function.addcslashes"> - <refnamediv> - <refname>AddCSlashes</refname> - <refpurpose>Marca una cadena con barras al estilo del C</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>addcslashes</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>string <parameter>listcar</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una cadena con barras invertidas antes de los caracteres - listados en el parámetro <parameter>listcar</parameter>. También - marca <literal>\n</literal>, <literal>\r</literal> etc. Al estilo - del C, los caracteres con códico ASCII inferior a 32 y superior a - 126 son convertidos a representación octal. Tenga cuidado cuando - marque caracteres alfanuméricos. Puede especificar un rango en - <parameter>listcar</parameter> como el "\0..\37", que marcaría - todos los caracteres con código ASCII entre 0 y 31. - <example> - <title>Ejemplo de <function>addcslashes</function></title> - <programlisting role="php"> -$tradformado = addcslashes ($no_transf, "\0..\37!@\177..\377"); - </programlisting> - </example> - <note> - <simpara> - Añadida en PHP4b3-dev.</simpara> - </note> - </para> - <para> - Vea también <function>stripcslashes</function>, - <function>stripslashes</function>, - <function>htmlspecialchars</function>, - <function>htmlspecialchars</function>, y - <function>quotemeta</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.addslashes"> - <refnamediv> - <refname>AddSlashes</refname> - <refpurpose>Marca una cadena con barras</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>addslashes</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una cadena con barras invertidas frente a los caracteres - que necesitan marcarse en consultas de bases de datos, etc. Estos - son la comilla simple (<literal>'</literal>), comilla doble - (<literal>"</literal>), barra invertida (<literal>\</literal>) - y NUL (el byte nulo). - </para> - <para> - Vea también <function>stripslashes</function>, - <function>htmlspecialchars</function>, y - <function>quotemeta</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.bin2hex"> - <refnamediv> - <refname>bin2hex</refname> - <refpurpose> - Convierte datos binarios en su representación hexadecimal - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>bin2hex</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una cadena ASCII que contiene la representación hexadecimal - de <parameter>cad</parameter>. La conversión se realiza byte a byte, - con los 4 bits superiores primero. - </para> - </refsect1> - </refentry> - - <refentry id="function.chop"> - <refnamediv> - <refname>chop</refname> - <refpurpose>Elimina espacios sobrantes al final</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>chop</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve la cadena argumento sin los espacios sobrantes, - incluyendo los saltos de línea. - <example> - <title>Ejemplo de <function>chop</function></title> - <programlisting role="php"> -$recortada = chop ($linea); - </programlisting> - </example> - </para> - <para> - Vea también <function>trim</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.chr"> - <refnamediv> - <refname>chr</refname> - <refpurpose>Devuelve un caracter específico</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>chr</function></funcdef> - <paramdef>int <parameter>ascii</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una cadena de un caracter que congiene el caracter - especificado por <parameter>ascii</parameter>. - <example> - <title>Ejemplo de <function>chr</function></title> - <programlisting role="php"> -$cad .= chr (27); /* añade un caracter de escape al final de $cad */ - -/* A veces esto es más útil */ - -$cad = sprintf ("La cadena termina en escape: %c", 27); - </programlisting> - </example> - Esta función complementa a <function>ord</function>. Vea también - <function>sprintf</function> con una cadena de formato - <literal>%c</literal>. - </para> - </refsect1> - </refentry> - - <refentry id="function.chunk-split"> - <refnamediv> - <refname>chunk_split</refname> - <refpurpose>Divide una cadena en trozos más pequeños</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>chunk_split</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - <paramdef>int - <parameter><optional>tamatrozo</optional></parameter> - </paramdef> - <paramdef>string - <parameter><optional>final</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Se puede utilizar para trocear una cadena en pedazos más pequeños, - lo que es útil, p.ej., para convertir la salida de la función <link - linkend="function.base64-encode">base64_encode</link> a la semántica - del RFC 2045. Inserta la cadena <parameter>final</parameter> cada - <parameter>tamatrozo</parameter> (por defecto vale 76) caracteres. - Devuelve la nueva cadena y deja intacta la original. - <example> - <title>Ejemplo de <function>chunk_split</function></title> - <programlisting role="php"> -# formatear $datos usando la semántica del RFC 2045 - -$nueva_cad = chunk_split (base64_encode($datos)); - </programlisting> - </example> - Esta función es notablemente más rápida que - <function>ereg_replace</function>. - <note> - <para> - Esta función se añadió en la 3.0.6. - </para> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.convert-cyr-string"> - <refnamediv> - <refname>convert_cyr_string</refname> - <refpurpose> - Convierte de un juego de caracteres Cirílico a otro - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>convert_cyr_string</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>string <parameter>desde</parameter></paramdef> - <paramdef>string <parameter>hasta</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función convierte la cadena dada de un juego de caracteres - Cirílico a otro. Los argumentos <parameter>desde</parameter> y - <parameter>hasta</parameter> son caracteres sencillos que - representan los juegos de caracteres Cirílicos fuente y destino. - Los tipos soportados son: - <itemizedlist> - <listitem> - <simpara> - k - koi8-r - </simpara> - </listitem> - <listitem> - <simpara> - w - windows-1251 - </simpara> - </listitem> - <listitem> - <simpara> - i - iso8859-5 - </simpara> - </listitem> - <listitem> - <simpara> - a - x-cp866 - </simpara> - </listitem> - <listitem> - <simpara> - d - x-cp866 - </simpara> - </listitem> - <listitem> - <simpara> - m - x-mac-cyrillic - </simpara> - </listitem> - </itemizedlist> - </para> - </refsect1> - </refentry> - - <refentry id="function.count-chars"> - <refnamediv> - <refname>count_chars</refname> - <refpurpose> - Devuelve información sobre los caracteres usados en una cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>count_chars</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - <paramdef> - <parameter> - <optional>modo</optional> - </parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Cuenta el número de apariciones de cada valor de byte (0..255) - en <parameter>cadena</parameter> y lo devuelve de varias maneras. - El parámetro opcional <parameter>modo</parameter> vale por defecto - 0. Dependiendo de <parameter>modo</parameter>, - <function>count_chars</function> puede devolver: - <itemizedlist> - <listitem> - <simpara> - 0 - una matriz con el valor del byte como clave y la frecuencia - de cada uno como valor. - </simpara> - </listitem> - <listitem> - <simpara> - 1 - como el 0, pero listando únicamente los valores de byte con - frecuencia superior a cero. - </simpara> - </listitem> - <listitem> - <simpara> - 2 - como el 0, pero listando únicamente los valores de byte con - frecuencia igual a 0. - </simpara> - </listitem> - <listitem> - <simpara> - 3 - se devuelve una cadena que contiene todos los valores de byte - utilizados. - </simpara> - </listitem> - <listitem> - <simpara> - 4 - se devuelve una cadena que contiene todos los valores de byte - no utilizados. - </simpara> - </listitem> - </itemizedlist> - </para> - <note> - <para> - Esta función se añadió en el PHP 4.0. - </para> - </note> - </refsect1> - </refentry> - - <refentry id="function.crc32"> - <refnamediv> - <refname>crc32</refname> - <refpurpose>Calcula el polinomio crc32 de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>crc32</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Genera el polinomio de comprobación de reduncancia cíclica de 32 bits - de <parameter>cad</parameter>. Se suele utilizar para validad la - integridad de los datos transmitidos. - </para> - <para> - Vea también: <function>md5</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.crypt"> - <refnamediv> - <refname>crypt</refname> - <refpurpose>Encripta una cadena mediante DES</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>crypt</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>string - <parameter><optional>semilla</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>crypt</function> encriptará una cadena utilizando el - método estándar de encriptación del Unix <abbrev>DES</abbrev>. - Los argumentos son una cadena a encriptar y una cadena semilla - de 2 caracteres en la que basar la encriptación. Vea la página de - manual de Unix sobre crypt para más información. - </para> - <simpara> - Si el argumento de semilla no se proporciona, será generado - aleatoriamente por el PHP. - </simpara> - <simpara> - Algunos sistemas operativos soportan más de un tipo de encriptación. - De hecho, algunas veces la encriptación estándar DES es sustituída - por un algoritmo de encriptación basado en MD5. El tipo de - encriptación es disparado por el argumento semilla. En tiempo de - instalación, el PHP determina la capacidad de la función de - encriptación y aceptará semillas para otros tipos de encriptación. - Si no se proporciona la semilla, el PHP intentará generar una - semilla estándar DES de 2 caraceres por defecto, excepto si el - tipo de encriptación estándar del sistema es el MD5, en cuyo caso - se generará una semilla aleatoria compatible con MD5. El PHP - fija una constante llamada CRYPT_SALT_LENGTH que le especifica si - su sistema soporta una semilla de 2 caracteres o si se debe usar - la semilla de 12 caracteres del NDS. - </simpara> - <simpara> - La función estándar de encriptación <function>crypt</function> contiene - la semilla como los dos primeros caracteres de la salida. - </simpara> - <simpara> - En los sistemas en los que la función crypt() soporta múltiples - tipos de encriptación, las siguienes constantes son fijadas a - 0 ó 1 dependiendo de si está disponible el tipo dado: - </simpara> - <itemizedlist> - <listitem> - <simpara> - CRYPT_STD_DES - Encriptación DES estándar con semilla de 2 caracteres - </simpara> - </listitem> - <listitem> - <simpara> - CRYPT_EXT_DES - Encriptación DES extendida con semilla de 9 caracteres - </simpara> - </listitem> - <listitem> - <simpara> - CRYPT_MD5 - Encriptación MD5 con semilla de 12 caracteres y comenzando - por $1$ - </simpara> - </listitem> - <listitem> - <simpara> - CRYPT_BLOWFISH - Encriptación DES extendida con semilla de 16 caracteres - y comenzando por $2$ - </simpara> - </listitem> - </itemizedlist> - <simpara> - No hay función de desencriptado porque <function>crypt</function> - utiliza un algoritmo de una sola vía. - </simpara> - <simpara> - Vea también: <function>md5</function>. - </simpara> - </refsect1> - </refentry> - <refentry id="function.echo"> - <refnamediv> - <refname>echo</refname> - <refpurpose>Da salida a una o más cadenas</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef><function>echo</function></funcdef> - <paramdef>string <parameter>arg1</parameter></paramdef> - <paramdef>string - <parameter><optional>argn</optional>...</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Da salida a todos sus parámetros. - </simpara> - <para> - <function>echo</function> no es realmente una función (es una - sentencia del lenguaje) de modo que no se requiere el uso de - los paréntesis. - <example> - <title>Ejemplo de <function>echo</function></title> - <programlisting role="php"> -echo "Hola Mundo"; - -echo "Esto se extiende -por varias líneas. Los saltos de línea -también se envían"; - -echo "Esto se extiende\npor varias líneas. Los saltos de línea\ntambién se envían"; - </programlisting> - </example> - </para> - <note> - <para> - De hecho, si desea pasar más de un parámetro a echo no debe - encerrarlos entre paréntesis. - </para> - </note> - <simpara> - Vea también: - <function>print</function>, - <function>printf</function>, y - <function>flush</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.explode"> - <refnamediv> - <refname>explode</refname> - <refpurpose>Divide una cadena por otra</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>explode</function></funcdef> - <paramdef>string <parameter>separador</parameter></paramdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - <paramdef>int - <parameter><optional>limite</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una matriz de cadenas, cada una de las cuales es una - subcadena de <parameter>cadena</parameter> formada mediante su - división en las fronteras marcadas por la cadena - <parameter>separador</parameter>. Si se especifica <parameter>limite</parameter>, - la matriz devuelta contendrá un máximo de <parameter>limite</parameter> - elementos con el último conteniendo el resto de la - <parameter>cadena</parameter>. - </para> - <para> - <example> - <title>Ejemplo de <function>explode</function></title> - <programlisting role="php"> -$pizza = "trozo1 trozo2 trozo3 trozo4 trozo5 trozo6"; -$trozos = explode (" ", $pizza); - </programlisting> - </example> - </para> - <para> - Vea también <function>split</function> e - <function>implode</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.get-html-translation-table"> - <refnamediv> - <refname>get_html_translation_table</refname> - <refpurpose> - Devuelve la tabla de traducción utilizada por - <function>htmlspecialchars</function> y - <function>htmlentities</function> - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string - <function>get_html_translation_table</function> - </funcdef> - <paramdef>int <parameter>tabla</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>get_html_translation_table</function> devolverá la - tabla de traducción que se usa internamente para - <function>htmlspecialchars</function> y - <function>htmlentities</function>. Hay dos nuevas definiciones - (<parameter>HTML_ENTITIES</parameter>, - <parameter>HTML_SPECIALCHARS</parameter>) que le permiten - especificar la tabla deseada. - <example> - <title>Ejemplo de Tabla de Traducción</title> - <programlisting role="php"> -$trad = get_html_translation_table (HTML_ENTITIES); -$cad = "Hallo &amp; &lt;Frau> &amp; Kr&auml;mer"; -$codif = strtr ($cad, $trad); - </programlisting> - </example> - La variable <literal>$codif</literal> contendrá ahora: "Hallo - &amp;<sgmltag>amp</sgmltag>; - &amp;<sgmltag>lt</sgmltag>;Frau&amp;<sgmltag>gt</sgmltag>; - &amp;<sgmltag>amp</sgmltag>; Kr&amp;<sgmltag>auml</sgmltag>;mer". - </para> - <para> - Lo interesante es usar la función <function>array_flip</function> - para cambiar la dirección de la traducción. - <informalexample> - <programlisting role="php"> -$trad = array_flip ($trad); -$original = strtr ($cad, $trad); - </programlisting> - </informalexample> - El contenido de <literal>$original</literal> sería: "Hallo &amp; - &lt;Frau> &amp; Kr&auml;mer". - <note> - <para> - Esta función fue añadida en PHP 4.0. - </para> - </note> - </para> - <para> - Vea también: <function>htmlspecialchars</function>, - <function>htmlentities</function>, <function>strtr</function>, - y <function>array_flip</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.get-meta-tags"> - <refnamediv> - <refname>get_meta_tags</refname> - <refpurpose> - Extrae todas las etiquetas meta de un archivo y retorna una matriz - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>get_meta_tags</function></funcdef> - <paramdef>string <parameter>nombrefich</parameter></paramdef> - <paramdef>int - <parameter><optional>use_ruta_include</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Abre el <parameter>nombrefich</parameter> y lo trocea línea a línea - buscando etiquetas &lt;meta> de la forma - <example> - <title>Ejemplo de Etiquetas Meta</title> - <programlisting role="html"> -&lt;meta name="autor" content="nombre"> -&lt;meta name="etiquetas" content="documentación de php3"> -&lt;/head> &lt;!-- el proceso se detiene aquí --> - </programlisting> - </example> - (preste atención a los finales de línea - el PHP utiliza una - función nativa para trocear la entrada, de modo que un archivo - de Mac no funcionará en Unix). - </para> - <para> - El valor de la propiedad name queda como clave y el valor de la - propiedad content queda como el valor de la matriz devuelta, de - modo que pueda usar fácilmente funciones estándar de matrices para - recorrerla o para acceder a valores individuales. Los caracteres - especiales en el valor de name son sustituídos por '_' y el resto - es convertido a minúsculas. - </para> - <para> - Fijando <parameter>use_ruta_include</parameter> a 1 hará que el - PHP intente abrir el archivo a través de la ruta de inclusión. - </para> - </refsect1> - </refentry> - - <refentry id="function.hebrev"> - <refnamediv> - <refname>hebrev</refname> - <refpurpose> - Convierte Hebreo lógico a texto visual - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>hebrev</function></funcdef> - <paramdef>string <parameter>texto_hebreo</parameter></paramdef> - <paramdef>int - <parameter><optional>max_cars_por_linea</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - El parámetro opcional <parameter>max_cars_por_linea</parameter> - indica el máximo número de caracteres que se emitirán por línea. - La función intenta evitar cortar palabras. - </para> - <para> - Vea también <function>hebrevc</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.hebrevc"> - <refnamediv> - <refname>hebrevc</refname> - <refpurpose> - Convierte Hebreo lógico a texto visual con conversión de saltos - de línea - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>hebrevc</function></funcdef> - <paramdef>string <parameter>texto_hebreo</parameter></paramdef> - <paramdef>int - <parameter><optional>max_cars_por_linea</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta funcion es similar a <function>hebrev</function> con la - diferencia que convierte las nuevas líneas (\n) a "&lt;br&gt;\n". - El parámetro opcional <parameter>max_cars_por_linea</parameter> - indica el máximo número de caracteres que se emitirán por línea. - La función intenta evitar cortar palabras. - </para> - <para> - Vea también <function>hebrev</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.htmlentities"> - <refnamediv> - <refname>htmlentities</refname> - <refpurpose> - Convierte todos los caracteres aplicables a entidades HTML - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>htmlentities</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función es del todo idéntica a <function>htmlspecialchars</function>, - excepto que traduce todos los caracteres que tienen equivalente - como entidad HTML. - </para> - <para> - Actualmente se utiliza el juego de caracteres ISO-8859-1. - </para> - <para> - Vea también <function>htmlspecialchars</function> y - <function>nl2br</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.htmlspecialchars"> - <refnamediv> - <refname>htmlspecialchars</refname> - <refpurpose> - Convierte caracteres especiales a entidades HTML - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>htmlspecialchars</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Ciertos caracteres tienen significados especiales en HTML, y deben - ser representados por entidades HTML si se desea preservar su - significado. Esta función devuelve una cadena con dichas conversiones - realizadas. - </para> - <simpara> - Esta función es útil para evitar que el texo entrado por el usuario - contenga marcas HTML, como ocurre en aplicaciones de foros o - libros de visita. - </simpara> - <para> - Actualmente, las traducciones hechas son: - <itemizedlist> - <listitem> - <simpara> - '&amp;' (ampersand) se convierte en '&amp;amp;' - </simpara> - </listitem> - <listitem> - <simpara> - '&quot;' (doble comilla) se convierte en '&amp;quot;' - </simpara> - </listitem> - <listitem> - <simpara> - '&lt;' (menor que) se convierte en '&amp;lt;' - </simpara> - </listitem> - <listitem> - <simpara> - '&gt;' (mayor que) se convierte en '&amp;gt;' - </simpara> - </listitem> - </itemizedlist> - </para> - <para> - Nótese que esta función no traduce nada más que lo mostrado - más arriba. Para una traducción de entidades completa, vea - <function>htmlentities</function>. - </para> - <para> - Vea también <function>htmlentities</function> y - <function>nl2br</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.implode"> - <refnamediv> - <refname>implode</refname> - <refpurpose>Unir elementos de una matriz mediante una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>implode</function></funcdef> - <paramdef>string <parameter>cola</parameter></paramdef> - <paramdef>array <parameter>piezas</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una cadena que contiene una representación de todos los - elementos de la matriz en el mismo orden, pero con la cadena - <parameter>cola</parameter> en medio de los mismos. - <example> - <title>Ejemplo de <function>implode</function></title> - <programlisting role="php"> -$separada_dospuntos = implode (":", $matrizay); - </programlisting> - </example> - </para> - <simpara> - Vea también <function>explode</function>, <function>join</function>, - y <function>split</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.join"> - <refnamediv> - <refname>join</refname> - <refpurpose>Une elementos de una tabla mediante una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>join</function></funcdef> - <paramdef>string <parameter>cola</parameter></paramdef> - <paramdef>array <parameter>piezas</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - <function>join</function> es un alias para - <function>implode</function>, y es idéntica en todo. - </simpara> - <simpara> - Vea también <function>explode</function>, <function>implode</function>, - y <function>split</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.levenshtein"> - <refnamediv> - <refname>levenshtein</refname> - <refpurpose> - Calcula la distancia Levenshtein entre dos cadenas - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>levenshtein</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función devuelve la distancia Levenshtein entre las dos - cadenas argumento, ó -1 si alguna de las cadenas tiene más - de 255 caracteres. - </para> - <para> - La distancia Levenshtein se define como el mínimo número de - caracteres que se tienen que sustituir, insertar o borrar - para transformar <parameter>cad1</parameter> en - <parameter>cad2</parameter>. La complejidad del algoritmo es - <literal>O(m*n)</literal>, donde <literal>n</literal> y - <literal>m</literal> son las longitudes de <parameter>cad1</parameter> - y <parameter>cad2</parameter> (bastante bueno si se la compara con - <function>similar_text</function>, que es O(max(n,m)**3), pero - aún es cara). - </para> - <para> - Vea también <function>soundex</function>, - <function>similar_text</function> y - <function>metaphone</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.ltrim"> - <refnamediv> - <refname>ltrim</refname> - <refpurpose> - Elimina el espacio en blanco del principio de una cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ltrim</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función elimina el espacio en blanco del principio de una - cadena y devuelve la cadena resultante. Los caracteres de espacio - que elimina realmente son: "\n", "\r", "\t", "\v", "\0", - y el espacio en sí. - </para> - <para> - Vea también <function>chop</function> y <function>trim</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.md5"> - <refnamediv> - <refname>md5</refname> - <refpurpose>Calcula el hash md5 de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>md5</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Calcula el hash (extracto) MD5 de <parameter>cad</parameter> - usaneo el - <ulink url="&url.rfc;rfc1321.html">Algoritmo de Resumen de - Mensajes MD5 de RSA Data Security, Inc. </ulink>. - </para> - <para> - Vea también: <function>crc32</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.metaphone"> - <refnamediv> - <refname>metaphone</refname> - <refpurpose>Calcula la clave "metáfona" de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>metaphone</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Calcula la clave "metáfona" de <parameter>cad</parameter>. - </para> - <para> - Similarmente a <function>soundex</function>, metaphone crea la - misma clave para palabras que suenan parecidas. Es más precisa - que la función <function>soundex</function>, pues conoce las - reglas básicas de la pronunciación del Inglés. Las claves - metafónicas generadas son de longitud variable. - </para> - <para> - Metaphone fue desarrollado por Lawrence Philips - &lt;lphilips@verity.com>. Se describe en ["Practical - Algorithms for Programmers", Binstock &amp; Rex, Addison Wesley, - 1995]. - <note> - <para> - Esta función se añadió en PHP 4.0. - </para> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.nl2br"> - <refnamediv> - <refname>nl2br</refname> - <refpurpose>Convierte nuevas líneas a saltos de línea HTML</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>nl2br</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve la <parameter>cadena</parameter> con '&lt;BR&gt;' insertados - antes de cada nueva línea. - </para> - <para> - Vea también <function>htmlspecialchars</function>, - <function>htmlentities</function> y - <function>wordwrap</function>. - </para> - </refsect1> - </refentry> - <refentry id="function.ord"> - <refnamediv> - <refname>ord</refname> - <refpurpose>Devuelve el valor ASCII de un caracter</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ord</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve el valor ASCII del primer caracter de - <parameter>cadena</parameter>. Esta función complementa a - <function>chr</function>. - <example> - <title>Ejemplo de <function>ord</function></title> - <programlisting role="php"> -if (ord ($cad) == 10) { - echo "El primer caracter de \$cad es un salto de línea.\n"; -} - </programlisting> - </example> - </para> - <simpara> - Vea también <function>chr</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.parse-str"> - <refnamediv> - <refname>parse_str</refname> - <refpurpose>Divide la cadena en variables</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>parse_str</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Divide <parameter>cad</parameter> como si fuera la cadena de consulta - enviada por un URL y crea las variables en el ámbito actual. - </para> - <para> - <example> - <title>Usando <function>parse_str</function></title> - <programlisting role="php"> -$cad = "primero=valor&amp;segundo[]=esto+funciona&amp;segundo[]=otro"; -parse_str($cad); -echo $primero; /* escribe "valor" */ -echo $segundo[0]; /* escribe "esto funciona" */ -echo $segundo[1]; /* escribe "otro" */ - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.print"> - <refnamediv> - <refname>print</refname> - <refpurpose>Emite una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef><function>print</function></funcdef> - <paramdef>string <parameter>arg</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Emite <parameter>arg</parameter>. - </simpara> - <simpara> - Vea también: <function>echo</function>, <function>printf</function>, - y <function>flush</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.printf"> - <refnamediv> - <refname>printf</refname> - <refpurpose>Emite una cadena con formato</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>printf</function></funcdef> - <paramdef>string <parameter>formato</parameter></paramdef> - <paramdef>mixed - <parameter><optional>args</optional></parameter>... - </paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Produce una salida según el <parameter>formato</parameter>, que es - descrito en la documentación para <function>sprintf</function>. - </simpara> - <simpara> - Vea también: <function>print</function>, <function>sprintf</function>, - <function>sscanf</function>, <function>fscanf</function>, - y <function>flush</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.quoted-printable-decode"> - <refnamediv> - <refname>quoted_printable_decode</refname> - <refpurpose> - Convierte una cadena con marcación imprimible a una cadena de 8 bits - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string - <function>quoted_printable_decode</function> - </funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Esta función devuelve una cadena binaria de 8 bit que se corresponde - con la cadena con marcación imprimible decodificada. Esta función es - similar a <function>imap_qprint</function>, pero sin requerir que el - módulo IMAP funcione. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.quotemeta"> - <refnamediv> - <refname>quotemeta</refname> - <refpurpose>Quote meta characters</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>quotemeta</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una versión de la cadena con una barra invertida - (<literal>\</literal>) antes de cada caracter de este - conjunto: <screen>. \\ + * ? [ ^ ] ( $ )</screen> - </para> - <simpara> - Vea también <function>addslashes</function>, - <function>htmlentities</function>, - <function>htmlspecialchars</function>, - <function>nl2br</function>, y - <function>stripslashes</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.rtrim"> - <refnamediv> - <refname>rtrim</refname> - <refpurpose>Elimina espacios en blanco al final de la cadena.</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcdef>string <function>rtrim</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcsynopsis> - <para> - Devuelve la cadena argumento sin espacios en blanco ni saltos - de línea al final. Es un alias para <function>chop</function>. - <example> - <title>Ejemplo de <function>rtrim</function></title> - <programlisting role="php"> -$recortada = rtrim ($linea); - </programlisting> - </example> - </para> - <para> - Vea también <function>trim</function>, <function>ltrim</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.sscanf"> - <refnamediv> - <refname>sscanf</refname> - <refpurpose>Trocea la entrada desde una cadena según un formato dado</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>sscanf</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>string <parameter>formato</parameter></paramdef> - <paramdef>string - <parameter><optional>var1</optional></parameter>... - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - La función<function>sscanf</function> es la función de entrada análoga - de <function>printf</function>. <function>sscanf</function> lee del - parámetro de cadena <parameter>cad</parameter> y lo interpreta según el - <parameter>formato</parameter> especificado. Si sólo se pasan dos parámetros - a esta función, los valores devueltos se harán en una matriz. - <example> - <title>Ejemplo de <function>sscanf</function></title> - <programlisting role="php"> -// obteniendo el número de serie -$numserie = sscanf("SN/2350001","SN/%d"); -// y la fecha de fabricación -$fecha = "01 Enero 2000"; -list($dia, $mes, $anno) = sscanf($fecha,"%d %s %d"); -echo "El objeto $numserie fue fabricado el: $anno-".substr($mes,0,3)."-$dia\n"; - </programlisting> - </example> - Si se pasan los parámetros opcionales, la función devolverá el número de - valores asignados. Los parámetros opcionales deben ser pasados por - referencia. - <example> - <title>Ejemplo de <function>sscanf</function> - usando parámetros opcionales</title> - <programlisting role="php"> -// obtener autor y generar la ficha DocBook -$autor = "24\tLewis Carroll"; -$n = sscanf($autor,"%d\t%s %s", &amp;$id, &amp;$nombre, &amp;$apell); -echo "&lt;autor id='$id'&gt; - &lt;firstname&gt;$nombre&lt;/firstname&gt; - &lt;surname&gt;$apell&lt;/surname&gt; -&lt;/author&gt;\n"; - </programlisting> - </example> - </para> - <para> - Vea también: <function>fscanf</function>, <function>printf</function>, - y <function>sprintf</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.setlocale"> - <refnamediv> - <refname>setlocale</refname> - <refpurpose>Fija la información de localidad</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>setlocale</function></funcdef> - <paramdef>string <parameter>categoria</parameter></paramdef> - <paramdef>string <parameter>localidad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <parameter>categoria</parameter> es una cadena que especifica - la categoría de las funciones afectadas por el ajuste de localidad: - <itemizedlist> - <listitem> - <simpara> - LC_ALL para todas las funciones - </simpara> - </listitem> - <listitem> - <simpara> - LC_COLLATE para la comparación de cadenas - aún no incluída en el PHP - </simpara> - </listitem> - <listitem> - <simpara> - LC_CTYPE para la conversión y clasificación de caracteres, como por - ejemplo <function>strtoupper</function> - </simpara> - </listitem> - <listitem> - <simpara> - LC_MONETARY para localeconv() - aún no incluída en el PHP - </simpara> - </listitem> - <listitem> - <simpara> - LC_NUMERIC para el separador decimal - </simpara> - </listitem> - <listitem> - <simpara> - LC_TIME para el formato de fecha y hora con - <function>strftime</function> - </simpara> - </listitem> - </itemizedlist> - </para> - <para> - Si <parameter>localidad</parameter> es la cadena vacía - <literal>""</literal>, los nombres de localidad se fijarán a - partir de las variables de entorno con los mismos nombres de las - categorías anteriores, o desde "LANG". - </para> - <para> - Si la localidad es cero o <literal>"0"</literal>, el ajuste de - localidad no se ve afectado y sólo se devuelve el ajuste actual. - </para> - <para> - setlocale devuelve la nueva localidad, o &false; si la funcionalidad - de localización no está disponible en la plataforma, la localidad - especificada no existe o el nombre de categoría no es válido. - Un nombre de categoría no válido también produce un mensaje de - aviso. - </para> - </refsect1> - </refentry> - - <refentry id="function.similar-text"> - <refnamediv> - <refname>similar_text</refname> - <refpurpose> - Calcula la similitud entre dos cadenas - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>similar_text</function></funcdef> - <paramdef>string <parameter>primera</parameter></paramdef> - <paramdef>string <parameter>segunda</parameter></paramdef> - <paramdef>double - <parameter><optional>porcentaje</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función calcula la similitud entre dos cadenas según se describe - en Oliver [1993]. Nótese que esta implementación no utiliza una pila - como en el pseudo-código de Oliver, sino llamadas recursivas que pueden - o no acelerar el proceso completo. Nótese también que la complejidad - de este algoritmo es O(N**3), donde N es la longitud de la cadena - más larga. - </para> - <para> - Pasando una referencia como tercer argumento, - <function>similar_text</function> calculará para usted la similitud - como porcentaje. Devuelve el número de caracteres coincidentes en - ambas cadenas. - </para> - </refsect1> - </refentry> - - <refentry id="function.soundex"> - <refnamediv> - <refname>soundex</refname> - <refpurpose>Calcula la clave soundex de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>soundex</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Calcula la clave soundex de <parameter>cad</parameter>. - </para> - <para> - Las claves soundex tienen la propiedad de que las palabras que - se pronuncian de forma parecida tienen la misma clave, de modo - que se pueden usar para simplificar la búsqueda en las bases de - datos cuando se conoce la pronunciación pero no la transcripción. - Esta función soundex devuelve una cadena de 4 caracteres que - comienza por una letra. - </para> - <para> - Esta función soundex en particular es la descrita por Donald Knuth - en "The Art Of Computer Programming, vol. 3: Sorting And - Searching", Addison-Wesley (1973), pp. 391-392. - </para> - <para> - <example> - <title>Ejemplos de Soundex</title> - <programlisting role="php"> -soundex ("Euler") == soundex ("Ellery") == 'E460'; -soundex ("Gauss") == soundex ("Ghosh") == 'G200'; -soundex ("Knuth") == soundex ("Kant") == 'H416'; -soundex ("Lloyd") == soundex ("Ladd") == 'L300'; -soundex ("Lukasiewicz") == soundex ("Lissajous") == 'L222'; - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.sprintf"> - <refnamediv> - <refname>sprintf</refname> - <refpurpose>Devuelve una cadena con formato</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>sprintf</function></funcdef> - <paramdef>string <parameter>formato</parameter></paramdef> - <paramdef>mixed - <parameter><optional>args</optional></parameter>... - </paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Devuelve una cadena producida de acuerdo a la cadena de - <parameter>formato</parameter>. - </simpara> - <simpara> - La cadena de formato está compuesta por cero o más directivas: - caracteres ordinarios (excepto <literal>%</literal>) que son - copiados directamente al resultado, y <emphasis>especificaciones - de conversión</emphasis>, cada una de las cuales provoca la - obtención de su propio parámetro. Esto se aplica tanto a - <function>sprintf</function> como a <function>printf</function>. - </simpara> - <para> - Cada especificación de conversión consiste en uno de estos elementos, - por orden: - <orderedlist> - <listitem> - <simpara> - Un <emphasis>especificador de relleno</emphasis> opcional que - indica qué caracter se utilizará para rellenar el resultado hasta - el tamaño de cadena correcto. Este puede ser un espacio o un - <literal>0</literal> (caracter cero). El valor por defecto es - rellenar con espacios. Un caracter de relleno alternativo se puede - especificar prefijándolo con una comilla simple (<literal>'</literal>). - Vea los ejemplos más abajo. - </simpara> - </listitem> - <listitem> - <simpara> - Un <emphasis>especificador de alineación</emphasis> opcional que - indica si el resultado debe ser alineado a la izquierda o a la - derecha. Por defecto se alinea a la derecha; un caracter - <literal>-</literal> aquí lo justificará a la izquierda. - </simpara> - </listitem> - <listitem> - <simpara> - Un número opcional, un <emphasis>especificador de ancho</emphasis> - que dice el número de caracteres (mínimo) en que debería resultar - esta conversión. - </simpara> - </listitem> - <listitem> - <simpara> - Un <emphasis>especificador de precisión</emphasis> opcional que - indica cuántos dígitos decimales deben mostrarse para los números - en coma flotante. Esta opción no tienen efecto para otros tipos - que no sean double. (Otra función útil para formatear números - es <function>number_format</function>). - </simpara> - </listitem> - <listitem> - <para> - Un <emphasis>especificador de tipo</emphasis> que indica el tipo - a usar para tratar los datos de los argumentos. Los tipos posibles - son: - <simplelist> - <member> - <literal>%</literal> - un caracter literal de porcentaje. No se - precisa argumento. - </member> - <member> - <literal>b</literal> - el argumento es tratado como un entero y - presentado como un número binario. - </member> - <member> - <literal>c</literal> - el argumento es tratado como un entero, y - presentado como el caracter con dicho valor ASCII. - </member> - <member> - <literal>d</literal> - el argumento es tratado como un entero y - presentado como un número decimal. - </member> - <member> - <literal>f</literal> - el argumento es tratado como un doble y - presentado como un número de coma flotante. - </member> - <member> - <literal>o</literal> - el argumento es tratado como un entero, y - presentado como un número octal. - </member> - <member> - <literal>s</literal> - el argumento es tratado como una cadena y - es presentado como tal. - </member> - <member> - <literal>x</literal> - el argumento es tratado como un entero y - presentado como un número hexadecimal (con minúsculas). - </member> - <member> - <literal>X</literal> - el argumento es tratado como un entero y - presentado como un número hexadecimal (con mayúsculas). - </member> - </simplelist> - </para> - </listitem> - </orderedlist> - </para> - <simpara> - Vea también: <function>printf</function>, <function>sscanf</function>, - <function>fscanf</function>, y <function>number_format</function>. - </simpara> - </refsect1> - <refsect1> - <title>Ejemplos</title> - <para> - <example> - <title>Ejemplo de <function>sprintf</function>: enteros rellenos con ceros</title> - <programlisting role="php"> -$fechaiso = sprintf ("%04d-%02d-%02d", $anno, $mes, $dia); - </programlisting> - </example> - <example> - <title>Ejemplo de <function>sprintf</function>: formateando monedas</title> - <programlisting role="php"> -$pelas1 = 68.75; -$pelas2 = 54.35; -$pelas = $pelas1 + $pelas2; -// echo $pelas mostrará "123.1"; -$formateado = sprintf ("%01.2f", $pelas); -// echo $formateado mostrará "123.10" - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.strcasecmp"> - <refnamediv> - <refname>strcasecmp</refname> - <refpurpose> - Comparación de cadenas insensible a mayúsculas y minúsculas - y segura en modo binario - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strcasecmp</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve &lt; 0 si <parameter>cad1</parameter> es menor que - <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> - es mayor que <parameter>cad2</parameter>, y 0 si son iguales. - <example> - <title>Ejemplo de <function>strcasecmp</function></title> - <programlisting role="php"> -$var1 = "Hello"; -$var2 = "hello"; -if (!strcasecmp ($var1, $var2)) { - echo '$var1 es igual a $var2 en una comparación sin tener en cuenta ' - .'mayúsculas o minúsculas'; -} - </programlisting> - </example> - </para> - <simpara> - Vea también <function>ereg</function>, <function>strcmp</function>, - <function>substr</function>, <function>stristr</function>, y - <function>strstr</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.strchr"> - <refnamediv> - <refname>strchr</refname> - <refpurpose> - Encuentra la primera aparición de un caracter - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strchr</function></funcdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - <paramdef>string <parameter>aguja</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función es un alias para <function>strstr</function>, y es - idéntica en todo. - </para> - </refsect1> - </refentry> - - <refentry id="function.strcmp"> - <refnamediv> - <refname>strcmp</refname> - <refpurpose>Comparación de cadenas con seguridad binaria</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strcmp</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Devuelve &lt; 0 si <parameter>cad1</parameter> es menor que - <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> - es mayor que <parameter>cad2</parameter>, y 0 si son iguales. - </simpara> - <simpara> - Nótese que esta comparación es sensible a mayúsculas y minúsculas. - </simpara> - <simpara> - Vea también <function>ereg</function>, - <function>strcasecmp</function>, <function>substr</function>, - <function>stristr</function>, <function>strncmp</function>, - y <function>strstr</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.strcspn"> - <refnamediv> - <refname>strcspn</refname> - <refpurpose> - Encuentra la longitud del elemento inicial que no coincide - con la máscara - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strcspn</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Devuelve la longitud del segmento inicial de - <parameter>cad1</parameter> que <emphasis>no</emphasis> - contiene ninguno de los caracteres de <parameter>cad2</parameter>. - </simpara> - <simpara> - Vea también <function>strspn</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.strip-tags"> - <refnamediv> - <refname>strip_tags</refname> - <refpurpose>Elimina marcas HTML y PHP de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strip_tags</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>string - <parameter><optional>etiq_permitidas</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función intenta eliminar todas las etiquetas HTML y PHP de - la cadena dada. Causa error por precaución en caso de etiquetas - incompletas o falsas. Utiliza la misma máquina de estados para - eliminar las etiquetas que la función <function>fgetss</function>. - </para> - <para> - Puede usar el parámetro opcional para especificar las etiquetas - que no deben eliminarse. - <note> - <para> - <parameter>etiq_permitidas</parameter> fue añadido en PHP 3.0.13, - PHP4B3. - </para> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.stripcslashes"> - <refnamediv> - <refname>stripcslashes</refname> - <refpurpose> - Desmarca la cadena marcada con <function>addcslashes</function> - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>stripcslashes</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una cadena con las barras invertidas eliminadas. - Reconoce las marcas tipo C <literal>\n</literal>, - <literal>\r</literal> ..., y la representación octal y - hexadecimal. - <note> - <simpara> - Añadida en PHP4b3-dev. - </simpara> - </note> - </para> - <simpara> - Vea también <function>addcslashes</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.stripslashes"> - <refnamediv> - <refname>stripslashes</refname> - <refpurpose> - Desmarca la cadena marcada con <function>addslashes</function> - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>stripslashes</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve una cadena con las barras invertidas eliminadas - (<literal>\'</literal> se convierte en <literal>'</literal>, - etc.). Las barras invertidas dobles se convierten en sencillas. - </para> - <simpara> - Vea también <function>addslashes</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.stristr"> - <refnamediv> - <refname>stristr</refname> - <refpurpose> - <function>strstr</function> sin tener en cuenta - mayúsculas o minúsculas - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>stristr</function></funcdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - <paramdef>string <parameter>aguja</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve todo el <parameter>pajar</parameter> desde la primera - aparición de la <parameter>aguja</parameter>, siendo el - <parameter>pajar</parameter> examinado sin tener en cuenta - mayúsculas o minúsculas. - </para> - <para> - Si la <parameter>aguja</parameter> no se encuentra, devuelve - &false;. - </para> - <para> - Si la <parameter>aguja</parameter> no es una cadena, es convertida - a entero y usada como código de un carácter ASCII. - </para> - <para> - Vea también <function>strchr</function>, - <function>strrchr</function>, <function>substr</function>, y - <function>ereg</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strlen"> - <refnamediv> - <refname>strlen</refname> - <refpurpose>Obtiene la longitud de la cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strlen</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve la longitud de la <parameter>cadena</parameter>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strnatcmp"> - <refnamediv> - <refname>strnatcmp</refname> - <refpurpose> - Compara cadenas usando un algoritmo de "orden natural" - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strnatcmp</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función implementa un algoritmo de comparación que ordena - las cadenas alfanuméricas como lo haría un ser humano, que es lo - que se denomina "orden natural". A continuación se puede ver un - ejemplo de la diferencia entre este algoritmo y los algoritmos de - ordenación de cadenas habituales en los ordenadores (utilizados - en <function>strcmp</function>): - <informalexample> - <programlisting> -$matriz1 = $matriz2 = array ("img12.png","img10.png","img2.png","img1.png"); -echo "Comparación de cadenas estándar\n"; -usort($matriz1,"strcmp"); -print_r($matriz1); -echo "\nComparación de cadenas en orden natural\n"; -usort($matriz2,"strnatcmp"); -print_r($matriz2); - </programlisting> - </informalexample> - El código anterior generará la siguiente salida: - <informalexample> - <programlisting> -Comparación de cadenas estándar -Array -( - [0] =&gt; img1.png - [1] =&gt; img10.png - [2] =&gt; img12.png - [3] =&gt; img2.png -) - -Comparación de cadenas en orden natural -Array -( - [0] =&gt; img1.png - [1] =&gt; img2.png - [2] =&gt; img10.png - [3] =&gt; img12.png -) - </programlisting> - </informalexample> - Para más información, vea la página de Martin Pool sobre - <ulink url="&url.strnatcmp;">Comparación de Cadenas en - Orden Natural</ulink>. - </para> - <simpara> - De forma similar a otras funciones de comparación de cadenas, - esta devuelve &lt; 0 si <parameter>cad1</parameter> es menor que - <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> - es mayor que <parameter>cad2</parameter>, y 0 si son iguales. - </simpara> - <simpara> - Nótese que esta comparación es sensible a mayúsculas y minúsculas. - </simpara> - <simpara> - Vea también <function>ereg</function>, - <function>strcasecmp</function>, <function>substr</function>, - <function>stristr</function>, <function>strcmp</function>, - <function>strncmp</function>, <function>strnatcasecmp</function>, - y <function>strstr</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.strnatcasecmp"> - <refnamediv> - <refname>strnatcasecmp</refname> - <refpurpose> - Comparación de cadenas insensible a mayúsculas y minúsculas - usando un algoritmo de "orden natural" - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strnatcasecmp</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función implementa un algoritmo de comparación que ordena - las cadenas alfanuméricas como lo haría un ser humano. El - comportamiento de esta función es similar a - <function>strnatcmp</function>, pero la comparación no es - sensible a mayúsculas y minúsculas. Para más información, - vea la página de Martin Pool sobre - <ulink url="&url.strnatcmp;">Comparación de Cadenas en - Orden Natural</ulink>. - </para> - <simpara> - De forma similar a otras funciones de comparación de cadenas, - esta devuelve &lt; 0 si <parameter>cad1</parameter> es menor que - <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> - es mayor que <parameter>cad2</parameter>, y 0 si son iguales. - </simpara> - <simpara> - Vea también <function>ereg</function>, - <function>strcasecmp</function>, <function>substr</function>, - <function>stristr</function>, <function>strcmp</function>, - <function>strncmp</function>, <function>strnatcmp</function>, - y <function>strstr</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.strncmp"> - <refnamediv> - <refname>strncmp</refname> - <refpurpose> - Comparación de los n primeros caracteres de cadenas, con - seguridad binaria - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strncmp</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - <paramdef>int <parameter>largo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función es similar a <function>strcmp</function>, con la - diferencia que se puede especificar el (límite superior del) - número de caractares (<parameter>largo</parameter>) de cada - cadena que se usarán en la comparación. Si alguna de las cadenas - es menor que el <parameter>largo</parameter>, se usará su - longitud para la comparación. - </para> - <simpara> - - Devuelve &lt; 0 si <parameter>cad1</parameter> es menor que - <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> - es mayor que <parameter>cad2</parameter>, y 0 si son iguales. - </simpara> - <simpara> - Nótese que esta comparación es sensible a mayúsculas y minúsculas. - </simpara> - <simpara> - Vea también <function>ereg</function>, - <function>strcasecmp</function>, <function>substr</function>, - <function>stristr</function>, <function>strcmp</function>, - y <function>strstr</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.str-pad"> - <refnamediv> - <refname>str_pad</refname> - <refpurpose>Rellena una cadena con otra hasta una longitud dada</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>str_pad</function></funcdef> - <paramdef>string <parameter>entrada</parameter></paramdef> - <paramdef>int <parameter>tama_relleno</parameter></paramdef> - <paramdef>string - <parameter><optional>cad_relleno</optional></parameter></paramdef> - <paramdef>int - <parameter><optional>tipo_relleno</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función rellena la cadena <parameter>entrada</parameter> por - la derecha, la izquierda o por ambos lados hasta el largo indicado. - Si no se especifica el argumento opcional - <parameter>cad_relleno</parameter>, <parameter>entrada</parameter> - es rellenada con espacios. En caso contrario, será rellenada con - los caracteres de <parameter>cad_relleno</parameter> hasta el límite. - </para> - - <para> - El argumento opcional <parameter>tipo_relleno</parameter> puede valer - STR_PAD_RIGHT, STR_PAD_LEFT, o STR_PAD_BOTH. Si no se especifica, se - asume que vale STR_PAD_RIGHT. - </para> - - <para> - Si el valor de <parameter>tama_relleno</parameter> es negativo o menor - que la longitud de la cadena de entrada, no se produce rellenado - alguno. - </para> - - <para> - <example> - <title>Ejemplo de <function>str_pad</function></title> - <programlisting role="php"> -$entrada = "Alien"; -print str_pad($entrada, 10); // produce "Alien " -print str_pad($entrada, 10, "-=", STR_PAD_LEFT); // produce "-=-=-Alien" -print str_pad($entrada, 10, "_", STR_PAD_BOTH); // produce "__Alien___" - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.strpos"> - <refnamediv> - <refname>strpos</refname> - <refpurpose> - Encuentra la posición de la primera aparición de una cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strpos</function></funcdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - <paramdef>string <parameter>aguja</parameter></paramdef> - <paramdef>int - <parameter><optional>desplazamiento</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve la posición numérica de la primera aparición de la - <parameter>aguja</parameter> en la cadena - <parameter>pajar</parameter>. A diferencia de - <function>strrpos</function>, esta función puede tomar una - cadena completa como <parameter>aguja</parameter> y se utilizará - en su totalidad. - </para> - <para> - Si la <parameter>aguja</parameter> no es hayada, devuelve &false;. - <note> - <para> - Es fácil confundir los valores de retorno para "caracter encontrado - en la posición 0" y "caracter no encontrado". Aquí se indica cómo - detectar la diferencia: - <informalexample> - <programlisting role="php"> -// en PHP 4.0b3 y posteriores: -$pos = strpos ($micadena, "b"); -if ($pos === false) { // nota: tres signos igual - // no encontrado ... -} - -// en versiones anteriores a la 4.0b3: -$pos = strpos ($micadena, "b"); -if (is_string ($pos) &amp;&amp; !$pos) { - // no encontrado ... -} - </programlisting> - </informalexample> - </para> - </note> - </para> - <para> - Si la <parameter>aguja</parameter> no es una cadena, se convierte - a entero y se aplica como el valor ordinal de un caracter. - </para> - <para> - El parámetro opcional <parameter>desplazamiento</parameter> le permite - especificar a partir de qué caracter del <parameter>pajar</parameter> - comenzar a buscar. La posición devuelta es aún relativa al comienzo - de <parameter>pajar</parameter>. - </para> - <para> - Vea también <function>strrpos</function>, - <function>strrchr</function>, <function>substr</function>, - <function>stristr</function>, y <function>strstr</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strrchr"> - <refnamediv> - <refname>strrchr</refname> - <refpurpose> - Encuentra la última aparición de un caracter en una cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strrchr</function></funcdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - <paramdef>string <parameter>aguja</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función devuelve la porción del - <parameter>pajar</parameter> que comienza en la última aparición - de la <parameter>aguja</parameter> y continúa hasta el final - del <parameter>pajar</parameter>. - </para> - <para> - Devuelve &false; si la <parameter>aguja</parameter> no es hallada. - </para> - <para> - Si la <parameter>aguja</parameter> contiene más de un caracter, - sólo se usará el primero. - </para> - <para> - Si la <parameter>aguja</parameter> no es una cadena, se convierte - a entero y se aplica como el valor ordinal de un caracter. - <example> - <title>Ejemplo de <function>strrchr</function></title> - <programlisting role="php"> -// obtener el último directorio de $PATH -$dir = substr (strrchr ($PATH, ":"), 1); - -// obtener todo tras el último salto de línea -$texto = "Line 1\nLine 2\nLine 3"; -$apell = substr (strrchr ($texto, 10), 1 ); - </programlisting> - </example> - </para> - <para> - Vea también <function>substr</function>, - <function>stristr</function>, y <function>strstr</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.str-repeat"> - <refnamediv> - <refname>str_repeat</refname> - <refpurpose>Repite una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>str_repeat</function></funcdef> - <paramdef>string <parameter>cad_entrada</parameter></paramdef> - <paramdef>int <parameter>veces</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve la <parameter>cad_entrada</parameter> repetida - <parameter>veces</parameter>. - <parameter>veces</parameter> debe ser mayor que 0. - </para> - <example> - <title>Ejemplo de <function>str_repeat</function></title> - <programlisting role="php"> -echo str_repeat ("-=", 10); - </programlisting> - </example> - <para> - Esto mostrará "-=-=-=-=-=-=-=-=-=-=". - </para> - <note> - <para> - Esta función fue añadida en el PHP 4.0. - </para> - </note> - </refsect1> - </refentry> - - <refentry id="function.strrev"> - <refnamediv> - <refname>strrev</refname> - <refpurpose>Invierte una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strrev</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuele la <parameter>cadena</parameter> invertida. - </para> - </refsect1> - </refentry> - - <refentry id="function.strrpos"> - <refnamediv> - <refname>strrpos</refname> - <refpurpose> - Encuentra la posición de la última aparición de un caracter en una cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strrpos</function></funcdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - <paramdef>char <parameter>aguja</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuele la posición numérica de la última aparición de - la <parameter>aguja</parameter> en el <parameter>pajar</parameter>. - Nótese que la aguja en este caso sólo puede ser un caracter único. - Si se pasa una cadena como aguja, sólo se utilizará el primer - caracter de la misma. - </para> - <para> - Si la <parameter>aguja</parameter> no es hayada, devuelve &false;. - </para> - <para> - Si la <parameter>aguja</parameter> no es una cadena, se convierte - a entero y se aplica como el valor ordinal de un caracter. - </para> - <para> - Vea también <function>strpos</function>, - <function>strrchr</function>, <function>substr</function>, - <function>stristr</function>, y <function>strstr</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strspn"> - <refnamediv> - <refname>strspn</refname> - <refpurpose> - Encuentra la longitud del segmento inicial que coincide con la - máscara - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>strspn</function></funcdef> - <paramdef>string <parameter>cad1</parameter></paramdef> - <paramdef>string <parameter>cad2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Devuelve la longitud del segmento inicial de - <parameter>cad1</parameter> que consiste por entero en - caracteres contenidos en <parameter>cad2</parameter>. - </simpara> - <para> - <informalexample> - <programlisting role="php"> -strspn ("42 es la respuesta. ¿Cuál es la pregunta ...?", "1234567890"); - </programlisting> - <para> - devolverá 2 como resultado. - </para> - </informalexample> - </para> - <simpara> - Vea también <function>strcspn</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.strstr"> - <refnamediv> - <refname>strstr</refname> - <refpurpose>Encuentra la primera aparición de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strstr</function></funcdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - <paramdef>string <parameter>aguja</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve todo el <parameter>pajar</parameter> desde la primera - aparición de la <parameter>aguja</parameter> hasta el final. - </para> - <para> - Si la <parameter>aguja</parameter> no es hayada, devuelve &false;. - </para> - <para> - Si la <parameter>aguja</parameter> no es una cadena, se convierte - a entero y se aplica como el valor ordinal de un caracter. - </para> - <para> - <note> - <para> - Nótese que esta función es sensible a mayúsculas y minúsculas. - Para búsquedas no sensibles, utilice <function>stristr</function>. - </para> - </note> - </para> - <para> - <example> - <title>Ejemplo de <function>strstr</function></title> - <programlisting role="php"> -$email = 'sterling@designmultimedia.com'; -$dominio = strstr ($email, '@'); -print $dominio; // imprime @designmultimedia.com - </programlisting> - </example> - </para> - <para> - Vea también <function>stristr</function>, - <function>strrchr</function>, <function>substr</function>, y - <function>ereg</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strtok"> - <refnamediv> - <refname>strtok</refname> - <refpurpose>Divide una cadena en elementos</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strtok</function></funcdef> - <paramdef>string <parameter>arg1</parameter></paramdef> - <paramdef>string <parameter>arg2</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>strtok</function> se usa para dividir en elementos una - cadena. Es decir, que si tiene una cadena como "Esta es una cadena - de ejemplo" podría dividirla en palabras individuales utilizando - el espacio como divisor. - <example> - <title>Ejemplo de <function>strtok</function></title> - <programlisting role="php"> -$cadena = "Esta es una cadena de ejemplo"; -$tok = strtok ($cadena," "); -while ($tok) { - echo "Palabra=$tok&lt;br>"; - $tok = strtok (" "); -} - </programlisting> - </example> - </para> - <para> - Nótese que sólo la primera llamada a strtok utiliza el argumento - cadena. Cada llamada subsiguiente necesita sólo el divisor a - utilizar, puesto que ella guarda la posición actual en la cadena. - Para comenzar de nuevo o para dividir otra cadena, simplemente - llame a strtok con el argumento de cadena y se inicializará. - Nótese que puede poner divisores múltiples como parámetro. La - cadena será dividida cuando alguno de los caracteres del argumento - sea hallado. - </para> - <para> - Además tenga cuidado si sus divisores valen "0", pues evalúa - como &false; en las expresiones condicionales. - </para> - <para> - Vea también <function>split</function> y - <function>explode</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strtolower"> - <refnamediv> - <refname>strtolower</refname> - <refpurpose>Pasa a minúsculas una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strtolower</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve la <parameter>cadena</parameter> con todas sus letras - en minúsculas. - </para> - <para> - Nótese que las letras son definidad por el locale actual. Esto - quiere decir que, por ejemplo, en el locale por defecto ("C"), - los caracteres como la Ñ no serán convertidos. - </para> - <example> - <title>Ejemplo de <function>strtolower</function></title> - <programlisting role="php"> -$cad = "María Tenía Un Corderito al que QUERÍA Mucho"; -$cad = strtolower($cad); -print $cad; # Visualiza maría tenía un corderito al que querÍa mucho - </programlisting> - </example> - <para> - Vea también <function>strtoupper</function> - y <function>ucfirst</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strtoupper"> - <refnamediv> - <refname>strtoupper</refname> - <refpurpose>Pasa a mayúsculas una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strtoupper</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Devuelve la <parameter>cadena</parameter> con todas sus letras - en mayúsculas. - </para> - <para> - Nótese que las letras son definidad por el locale actual. Esto - quiere decir que, por ejemplo, en el locale por defecto ("C"), - los caracteres como la ñ no serán convertidos. - </para> - <example> - <title>Ejemplo de <function>strtoupper</function></title> - <programlisting role="php"> -$cad = "María Tenía Un Corderito al que QUERÍA Mucho"; -$cad = strtoupper ($cad); -print $cad; # Visuaiza MARíA TENíA UN CORDERITO AL QUE QUERÍA MUCHO - </programlisting> - </example> - <para> - Vea también <function>strtolower</function> - and <function>ucfirst</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.str-replace"> - <refnamediv> - <refname>str_replace</refname> - <refpurpose> - Sustitiye todas las apariciones de la aguja en el pajar por la cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>str_replace</function></funcdef> - <paramdef>string <parameter>aguja</parameter></paramdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función sustituye todas las apariciones de la - <parameter>aguja</parameter> en el <parameter>pajar</parameter> - por la <parameter>cad</parameter> dada. Si no precisa reglas - especiales de sustitución, deberá usar siempre esta función en - lugar de <function>ereg_replace</function>.</para> - <para> - <example> - <title>Ejemplo de <function>str_replace</function></title> - <programlisting role="php"> -$bodytag = str_replace ("%cuerpo%", "negro", "&lt;body text=%cuerpo%>"); - </programlisting> - </example> - </para> - <para> - Esta función tiene seguridad binaria. - </para> - <note> - <para> - <function>str_replace</function> fue añadida en PHP 3.0.6, pero tuvo - errores hasta el PHP 3.0.8. - </para> - </note> - <para> - Vea también <function>ereg_replace</function> y - <function>strtr</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.strtr"> - <refnamediv> - <refname>strtr</refname> - <refpurpose>Traduce ciertos caracteres</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>strtr</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>string <parameter>desde</parameter></paramdef> - <paramdef>string <parameter>hasta</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función trabaja sobre <parameter>cad</parameter>, traduciendo - todas las apariciones de cada caracter en <parameter>desde</parameter> - por el caracter correspondiente en <parameter>hasta</parameter> y - devolviendo el resultado. - </para> - <para> - Si <parameter>desde</parameter> y <parameter>hasta</parameter> son - de distinta longitud, los caracteres extra en la más larga son - ignorados. - <example> - <title>Ejemplo de <function>strtr</function></title> - <programlisting role="php"> -$addr = strtr($addr, "äåö", "aao"); - </programlisting> - </example> - </para> - <para> - <function>strtr</function> puede llamarso sólo con dos argumentos. - Si se llama de esta manera, se comporta de otro modo: - <parameter>desde</parameter> debe ser entonces una matriz que - contenga pares cadena -> cadena que serán sustituídos en la - cadena fuente. <function>strtr</function> siempre buscará la - coincidencia más larga primero y *NO* intentará sustituir nada - en lo que haya trabajado ya. - </para> - <para> - Ejemplos: - <informalexample> - <programlisting role="php"> -$trad = array ("hola" =&gt; "hey", "hey" =&gt; "hola"); -echo strtr("hey a todos, dije hola", $trad) . "\n"; - </programlisting> - </informalexample> - Mostrará: "hola a todos, dije hey", - </para> - <note> - <simpara> - Esta característica (2 argumentos) fue añadida en el PHP 4.0 - </simpara> - </note> - <para> - Vea también <function>ereg_replace</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.substr"> - <refnamediv> - <refname>substr</refname> - <refpurpose>Devuelve parte de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>substr</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - <paramdef>int <parameter>comienzo</parameter></paramdef> - <paramdef>int - <parameter><optional>largo</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - substr devuelve la porción de <parameter>cadena</parameter> - especificada por los parámetros <parameter>comienzo</parameter> - y <parameter>largo</parameter>. - </para> - <para> - Si <parameter>comienzo</parameter> es positivo, la cadena devuelta - comenzará en dicho caracter de <parameter>cadena</parameter>. - </para> - <para> - Ejemplos: - <informalexample> - <programlisting role="php"> -$resto = substr ("abcdef", 1); // devuelve "bcdef" -$resto = substr ("abcdef", 1, 3); // devuelve "bcd" - </programlisting> - </informalexample> - </para> - <para> - Si <parameter>comienzo</parameter> es negativo, la cadena devuelta - comenzará en dicha posición desde el final de - <parameter>cadena</parameter>. - </para> - <para> - Ejemplos: - <informalexample> - <programlisting role="php"> -$resto = substr ("abcdef", -1); // devuelve "f" -$resto = substr ("abcdef", -2); // devuelve "ef" -$resto = substr ("abcdef", -3, 1); // devuelve "d" - </programlisting> - </informalexample> - </para> - <para> - Si se especifica <parameter>largo</parameter> y es positivo, la - cadena devuelta terminará <parameter>largo</parameter> caracteres - tras el <parameter>comienzo</parameter>. Si esto resulta en una - cadena con longitud negativa (porque el comienzo está pasado el - final de la cadena), la cadena devuelta contendrá únicamente el - caracter que haya en <parameter>comienzo</parameter>. - </para> - <para> - Si se especifica <parameter>largo</parameter> y es negativo, la - cadena devuelta terminará a <parameter>largo</parameter> caracteres - desde el final de <parameter>cadena</parameter>. Si esto resulta en una - cadena con longitud negativa, la cadena devuelta contendrá - únicamente el caracter que haya en <parameter>comienzo</parameter>. - </para> - <para> - Examples: - <informalexample> - <programlisting role="php"> -$resto = substr ("abcdef", 1, -1); // devuelve "bcde" - </programlisting> - </informalexample> - </para> - <para> - Vea también <function>strrchr</function> y - <function>ereg</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.substr-count"> - <refnamediv> - <refname>substr_count</refname> - <refpurpose>Cuenta el número de apariciones de la subcadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>substr_count</function></funcdef> - <paramdef>string <parameter>pajar</parameter></paramdef> - <paramdef>string <parameter>aguja</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>substr_count</function> devuelve el número de veces - que la subcadena <parameter>aguja</parameter> se encuentra en - la cadena <parameter>pajar</parameter>. - </para> - - <para> - <example> - <title>Ejemplo de <function>substr_count</function></title> - <programlisting> -print substr_count("This is a test", "is"); // prints out 2 - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.substr-replace"> - <refnamediv> - <refname>substr_replace</refname> - <refpurpose>Sustituye texto en una parte de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>substr_replace</function></funcdef> - <paramdef>string <parameter>cadena</parameter></paramdef> - <paramdef>string <parameter>sustituto</parameter></paramdef> - <paramdef>int <parameter>comienzo</parameter></paramdef> - <paramdef>int - <parameter><optional>largo</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>substr_replace</function> sustituye la parte de - <parameter>cadena</parameter> delimitada por los parámetros - <parameter>comienzo</parameter> y (opcionalmente) - <parameter>largo</parameter> por la cadena dada en - <parameter>sustituto</parameter>. Se devuelve el resultado. - </para> - <para> - Si <parameter>comienzo</parameter> es positivo, la sustitución - comenzará en dicha posición dentro de la <parameter>cadena</parameter>. - </para> - <para> - Si <parameter>comienzo</parameter> es negativo, la sustitución - comenzará en dicha posición pero contando desde el final de - <parameter>cadena</parameter>. - </para> - <para> - Si se especifica el <parameter>largo</parameter> y es positivo, - representa el largo de la porción de - <parameter>cadena</parameter> a sustituir. Si es negativo, - representa el número de caracteres desde el final de - <parameter>cadena</parameter> en los que dejar de sustituir. - Si no se especifica, valdrá por defecto - strlen(<parameter>cadena</parameter>); es decir, que acabará - la sustitución al final de <parameter>cadena</parameter>. - </para> - <para> - <example> - <title>Ejemplo de <function>substr_replace</function></title> - <programlisting role="php"> -&lt;?php -$var = 'ABCDEFGH:/MNRPQR/'; -echo "Original: $var&lt;hr&gt;\n"; - -/* Estos dos ejemplos sustituyen toda $var por 'bob'. */ -echo substr_replace ($var, 'bob', 0) . "&lt;br&gt;\n"; -echo substr_replace ($var, 'bob', 0, strlen ($var)) . "&lt;br&gt;\n"; - -/* Inserta 'bob' justo al inicio de $var. */ -echo substr_replace ($var, 'bob', 0, 0) . "&lt;br&gt;\n"; - -/* Los dos siguientes cambian 'MNRPQR' en $var por 'bob'. */ -echo substr_replace ($var, 'bob', 10, -1) . "&lt;br&gt;\n"; -echo substr_replace ($var, 'bob', -7, -1) . "&lt;br&gt;\n"; - -/* Borrar 'MNRPQR' de $var. */ -echo substr_replace ($var, '', 10, -1) . "&lt;br&gt;\n"; -?&gt; - </programlisting> - </example> - </para> - <para> - Vea también <function>str_replace</function> y - <function>substr</function>. - </para> - <note> - <simpara> - <function>substr_replace</function> fue añadida en el PHP 4.0. - </simpara> - </note> - </refsect1> - </refentry> - - <refentry id="function.trim"> - <refnamediv> - <refname>trim</refname> - <refpurpose> - Elimina espacios del principio y final de una cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>trim</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta función elimina los espacios en blanco del comienzo y del - final de una cadena y devuelve el resultado. Los caracteres de - espacio que elimina realmente son: "\n", "\r", "\t", "\v", "\0", - y el espacio en sí. - </para> - <para> - Vea también <function>chop</function> y - <function>ltrim</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.ucfirst"> - <refnamediv> - <refname>ucfirst</refname> - <refpurpose>Pasar a mayúsculas el primer caracter de una cadena</refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ucfirst</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Pone en mayúsculas el primer carácter de <parameter>cad</parameter> - si es alfabético. - </para> - <para> - Nótese que 'alfabético' está determinado por la localidad actual. - Por ejemplo, en la localidad por defecto "C", los caracteres como - la a con diéresis (ä) no serán convertidos. - <example> - <title>Ejemplo de <function>ucfirst</function></title> - <programlisting role="php"> -$texto = 'susanita tiene un ratón, un ratón chiquitín.'; -$texto = ucfirst ($texto); // $texto vale ahora: Susanita tiene un - // ratón, un ratón chiquitín. - </programlisting> - </example> - </para> - <para> - Vea también <function>strtoupper</function> y - <function>strtolower</function> - </para> - </refsect1> - </refentry> - - <refentry id="function.ucwords"> - <refnamediv> - <refname>ucwords</refname> - <refpurpose> - Pone en mayúsculas el primer caracter de cada palabra - de una cadena - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>ucwords</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Pasa a mayúsculas la primera letra de cada palabra en - <parameter>cad</parameter> si dicho caracter es alfabético. - <example> - <title>Ejemplo de <function>ucwords</function></title> - <programlisting role="php"> -$texto = "susanita tiene un ratón, un ratón chiquitín."; -$texto = ucwords($texto); // $texto vale ahora: Susanita Tiene Un - // Ratón, Un Ratón Chiquitín. - </programlisting> - </example> - </para> - <para> - Vea también <function>strtoupper</function>, - <function>strtolower</function> y <function>ucfirst</function>. - </para> - </refsect1> - </refentry> - - - <refentry id="function.wordwrap"> - <refnamediv> - <refname>wordwrap</refname> - <refpurpose> - Corta una cadena en un número dado de caracteres usando un - caracter de ruptura de cadenas. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descripción</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>wordwrap</function></funcdef> - <paramdef>string <parameter>cad</parameter></paramdef> - <paramdef>int - <parameter><optional>ancho</optional></parameter> - </paramdef> - <paramdef>string - <parameter><optional>ruptura</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Corta la cadena <parameter>cad</parameter> en la columna - especificada por el parámetro (opcional) <parameter>ancho</parameter>. - La línea se rompe utilizando el parámetro (opcional) - <parameter>ruptura</parameter>. - </para> - <para> - <function>wordwrap</function> automáticamente cortará en la - columna 75 y usará '\n' (nueva línea) si no se especifican - el <parameter>ancho</parameter> o la <parameter>ruptura</parameter>. - </para> - <para> - <example> - <title>Ejemplo de <function>wordwrap</function></title> - <programlisting role="php"> -$texto = "El veloz murciélago hindú comía feliz cardillo y kiwi."; -$textonuevo = wordwrap( $texto, 20 ); - -echo "$textonuevo\n"; - </programlisting> - </example> - </para> - <para> - Este ejemplo mostraría: - </para> - <para> - <informalexample> - <programlisting> -El veloz murciélago -hindú comía feliz cardillo y kiwi. - </programlisting> - </informalexample> - </para> - <para> - Vea también <function>nl2br</function>. - </para> - </refsect1> - </refentry> - - - </reference> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: +<reference id="ref.strings"> + <title>Funciones de cadenas</title> + <titleabbrev>Cadenas</titleabbrev> + + <partintro> + <simpara> + Todas estas funciones manipulan cadenas de varias maneras. En las + secciones sobre expresiones regulares y manejo de URL se pueden + encontrar secciones más especializadas. + </simpara> + </partintro> + + <refentry id="function.addcslashes"> + <refnamediv> + <refname>AddCSlashes</refname> + <refpurpose>Marca una cadena con barras al estilo del C</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>addcslashes</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>string <parameter>listcar</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una cadena con barras invertidas antes de los caracteres + listados en el parámetro <parameter>listcar</parameter>. También + marca <literal>\n</literal>, <literal>\r</literal> etc. Al estilo + del C, los caracteres con códico ASCII inferior a 32 y superior a + 126 son convertidos a representación octal. Tenga cuidado cuando + marque caracteres alfanuméricos. Puede especificar un rango en + <parameter>listcar</parameter> como el "\0..\37", que marcaría + todos los caracteres con código ASCII entre 0 y 31. + <example> + <title>Ejemplo de <function>addcslashes</function></title> + <programlisting role="php"> +$tradformado = addcslashes ($no_transf, "\0..\37!@\177..\377"); + </programlisting> + </example> + <note> + <simpara> + Añadida en PHP4b3-dev.</simpara> + </note> + </para> + <para> + Vea también <function>stripcslashes</function>, + <function>stripslashes</function>, + <function>htmlspecialchars</function>, + <function>htmlspecialchars</function>, y + <function>quotemeta</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.addslashes"> + <refnamediv> + <refname>AddSlashes</refname> + <refpurpose>Marca una cadena con barras</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>addslashes</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una cadena con barras invertidas frente a los caracteres + que necesitan marcarse en consultas de bases de datos, etc. Estos + son la comilla simple (<literal>'</literal>), comilla doble + (<literal>"</literal>), barra invertida (<literal>\</literal>) + y NUL (el byte nulo). + </para> + <para> + Vea también <function>stripslashes</function>, + <function>htmlspecialchars</function>, y + <function>quotemeta</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.bin2hex"> + <refnamediv> + <refname>bin2hex</refname> + <refpurpose> + Convierte datos binarios en su representación hexadecimal + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>bin2hex</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una cadena ASCII que contiene la representación hexadecimal + de <parameter>cad</parameter>. La conversión se realiza byte a byte, + con los 4 bits superiores primero. + </para> + </refsect1> + </refentry> + + <refentry id="function.chop"> + <refnamediv> + <refname>chop</refname> + <refpurpose>Elimina espacios sobrantes al final</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>chop</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve la cadena argumento sin los espacios sobrantes, + incluyendo los saltos de línea. + <example> + <title>Ejemplo de <function>chop</function></title> + <programlisting role="php"> +$recortada = chop ($linea); + </programlisting> + </example> + </para> + <para> + Vea también <function>trim</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.chr"> + <refnamediv> + <refname>chr</refname> + <refpurpose>Devuelve un caracter específico</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>chr</function></funcdef> + <paramdef>int <parameter>ascii</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una cadena de un caracter que congiene el caracter + especificado por <parameter>ascii</parameter>. + <example> + <title>Ejemplo de <function>chr</function></title> + <programlisting role="php"> +$cad .= chr (27); /* añade un caracter de escape al final de $cad */ + +/* A veces esto es más útil */ + +$cad = sprintf ("La cadena termina en escape: %c", 27); + </programlisting> + </example> + Esta función complementa a <function>ord</function>. Vea también + <function>sprintf</function> con una cadena de formato + <literal>%c</literal>. + </para> + </refsect1> + </refentry> + + <refentry id="function.chunk-split"> + <refnamediv> + <refname>chunk_split</refname> + <refpurpose>Divide una cadena en trozos más pequeños</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>chunk_split</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + <paramdef>int + <parameter><optional>tamatrozo</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>final</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Se puede utilizar para trocear una cadena en pedazos más pequeños, + lo que es útil, p.ej., para convertir la salida de la función <link + linkend="function.base64-encode">base64_encode</link> a la semántica + del RFC 2045. Inserta la cadena <parameter>final</parameter> cada + <parameter>tamatrozo</parameter> (por defecto vale 76) caracteres. + Devuelve la nueva cadena y deja intacta la original. + <example> + <title>Ejemplo de <function>chunk_split</function></title> + <programlisting role="php"> +# formatear $datos usando la semántica del RFC 2045 + +$nueva_cad = chunk_split (base64_encode($datos)); + </programlisting> + </example> + Esta función es notablemente más rápida que + <function>ereg_replace</function>. + <note> + <para> + Esta función se añadió en la 3.0.6. + </para> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.convert-cyr-string"> + <refnamediv> + <refname>convert_cyr_string</refname> + <refpurpose> + Convierte de un juego de caracteres Cirílico a otro + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>convert_cyr_string</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>string <parameter>desde</parameter></paramdef> + <paramdef>string <parameter>hasta</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función convierte la cadena dada de un juego de caracteres + Cirílico a otro. Los argumentos <parameter>desde</parameter> y + <parameter>hasta</parameter> son caracteres sencillos que + representan los juegos de caracteres Cirílicos fuente y destino. + Los tipos soportados son: + <itemizedlist> + <listitem> + <simpara> + k - koi8-r + </simpara> + </listitem> + <listitem> + <simpara> + w - windows-1251 + </simpara> + </listitem> + <listitem> + <simpara> + i - iso8859-5 + </simpara> + </listitem> + <listitem> + <simpara> + a - x-cp866 + </simpara> + </listitem> + <listitem> + <simpara> + d - x-cp866 + </simpara> + </listitem> + <listitem> + <simpara> + m - x-mac-cyrillic + </simpara> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="function.count-chars"> + <refnamediv> + <refname>count_chars</refname> + <refpurpose> + Devuelve información sobre los caracteres usados en una cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>count_chars</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + <paramdef> + <parameter> + <optional>modo</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Cuenta el número de apariciones de cada valor de byte (0..255) + en <parameter>cadena</parameter> y lo devuelve de varias maneras. + El parámetro opcional <parameter>modo</parameter> vale por defecto + 0. Dependiendo de <parameter>modo</parameter>, + <function>count_chars</function> puede devolver: + <itemizedlist> + <listitem> + <simpara> + 0 - una matriz con el valor del byte como clave y la frecuencia + de cada uno como valor. + </simpara> + </listitem> + <listitem> + <simpara> + 1 - como el 0, pero listando únicamente los valores de byte con + frecuencia superior a cero. + </simpara> + </listitem> + <listitem> + <simpara> + 2 - como el 0, pero listando únicamente los valores de byte con + frecuencia igual a 0. + </simpara> + </listitem> + <listitem> + <simpara> + 3 - se devuelve una cadena que contiene todos los valores de byte + utilizados. + </simpara> + </listitem> + <listitem> + <simpara> + 4 - se devuelve una cadena que contiene todos los valores de byte + no utilizados. + </simpara> + </listitem> + </itemizedlist> + </para> + <note> + <para> + Esta función se añadió en el PHP 4.0. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.crc32"> + <refnamediv> + <refname>crc32</refname> + <refpurpose>Calcula el polinomio crc32 de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>crc32</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Genera el polinomio de comprobación de reduncancia cíclica de 32 bits + de <parameter>cad</parameter>. Se suele utilizar para validad la + integridad de los datos transmitidos. + </para> + <para> + Vea también: <function>md5</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.crypt"> + <refnamediv> + <refname>crypt</refname> + <refpurpose>Encripta una cadena mediante DES</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>crypt</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>string + <parameter><optional>semilla</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>crypt</function> encriptará una cadena utilizando el + método estándar de encriptación del Unix <abbrev>DES</abbrev>. + Los argumentos son una cadena a encriptar y una cadena semilla + de 2 caracteres en la que basar la encriptación. Vea la página de + manual de Unix sobre crypt para más información. + </para> + <simpara> + Si el argumento de semilla no se proporciona, será generado + aleatoriamente por el PHP. + </simpara> + <simpara> + Algunos sistemas operativos soportan más de un tipo de encriptación. + De hecho, algunas veces la encriptación estándar DES es sustituída + por un algoritmo de encriptación basado en MD5. El tipo de + encriptación es disparado por el argumento semilla. En tiempo de + instalación, el PHP determina la capacidad de la función de + encriptación y aceptará semillas para otros tipos de encriptación. + Si no se proporciona la semilla, el PHP intentará generar una + semilla estándar DES de 2 caraceres por defecto, excepto si el + tipo de encriptación estándar del sistema es el MD5, en cuyo caso + se generará una semilla aleatoria compatible con MD5. El PHP + fija una constante llamada CRYPT_SALT_LENGTH que le especifica si + su sistema soporta una semilla de 2 caracteres o si se debe usar + la semilla de 12 caracteres del NDS. + </simpara> + <simpara> + La función estándar de encriptación <function>crypt</function> contiene + la semilla como los dos primeros caracteres de la salida. + </simpara> + <simpara> + En los sistemas en los que la función crypt() soporta múltiples + tipos de encriptación, las siguienes constantes son fijadas a + 0 ó 1 dependiendo de si está disponible el tipo dado: + </simpara> + <itemizedlist> + <listitem> + <simpara> + CRYPT_STD_DES - Encriptación DES estándar con semilla de 2 caracteres + </simpara> + </listitem> + <listitem> + <simpara> + CRYPT_EXT_DES - Encriptación DES extendida con semilla de 9 caracteres + </simpara> + </listitem> + <listitem> + <simpara> + CRYPT_MD5 - Encriptación MD5 con semilla de 12 caracteres y comenzando + por $1$ + </simpara> + </listitem> + <listitem> + <simpara> + CRYPT_BLOWFISH - Encriptación DES extendida con semilla de 16 caracteres + y comenzando por $2$ + </simpara> + </listitem> + </itemizedlist> + <simpara> + No hay función de desencriptado porque <function>crypt</function> + utiliza un algoritmo de una sola vía. + </simpara> + <simpara> + Vea también: <function>md5</function>. + </simpara> + </refsect1> + </refentry> + <refentry id="function.echo"> + <refnamediv> + <refname>echo</refname> + <refpurpose>Da salida a una o más cadenas</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef><function>echo</function></funcdef> + <paramdef>string <parameter>arg1</parameter></paramdef> + <paramdef>string + <parameter><optional>argn</optional>...</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Da salida a todos sus parámetros. + </simpara> + <para> + <function>echo</function> no es realmente una función (es una + sentencia del lenguaje) de modo que no se requiere el uso de + los paréntesis. + <example> + <title>Ejemplo de <function>echo</function></title> + <programlisting role="php"> +echo "Hola Mundo"; + +echo "Esto se extiende +por varias líneas. Los saltos de línea +también se envían"; + +echo "Esto se extiende\npor varias líneas. Los saltos de línea\ntambién se envían"; + </programlisting> + </example> + </para> + <note> + <para> + De hecho, si desea pasar más de un parámetro a echo no debe + encerrarlos entre paréntesis. + </para> + </note> + <simpara> + Vea también: + <function>print</function>, + <function>printf</function>, y + <function>flush</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.explode"> + <refnamediv> + <refname>explode</refname> + <refpurpose>Divide una cadena por otra</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>explode</function></funcdef> + <paramdef>string <parameter>separador</parameter></paramdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + <paramdef>int + <parameter><optional>limite</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una matriz de cadenas, cada una de las cuales es una + subcadena de <parameter>cadena</parameter> formada mediante su + división en las fronteras marcadas por la cadena + <parameter>separador</parameter>. Si se especifica <parameter>limite</parameter>, + la matriz devuelta contendrá un máximo de <parameter>limite</parameter> + elementos con el último conteniendo el resto de la + <parameter>cadena</parameter>. + </para> + <para> + <example> + <title>Ejemplo de <function>explode</function></title> + <programlisting role="php"> +$pizza = "trozo1 trozo2 trozo3 trozo4 trozo5 trozo6"; +$trozos = explode (" ", $pizza); + </programlisting> + </example> + </para> + <para> + Vea también <function>split</function> e + <function>implode</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.get-html-translation-table"> + <refnamediv> + <refname>get_html_translation_table</refname> + <refpurpose> + Devuelve la tabla de traducción utilizada por + <function>htmlspecialchars</function> y + <function>htmlentities</function> + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string + <function>get_html_translation_table</function> + </funcdef> + <paramdef>int <parameter>tabla</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>get_html_translation_table</function> devolverá la + tabla de traducción que se usa internamente para + <function>htmlspecialchars</function> y + <function>htmlentities</function>. Hay dos nuevas definiciones + (<parameter>HTML_ENTITIES</parameter>, + <parameter>HTML_SPECIALCHARS</parameter>) que le permiten + especificar la tabla deseada. + <example> + <title>Ejemplo de Tabla de Traducción</title> + <programlisting role="php"> +$trad = get_html_translation_table (HTML_ENTITIES); +$cad = "Hallo &amp; &lt;Frau> &amp; Kr&auml;mer"; +$codif = strtr ($cad, $trad); + </programlisting> + </example> + La variable <literal>$codif</literal> contendrá ahora: "Hallo + &amp;<sgmltag>amp</sgmltag>; + &amp;<sgmltag>lt</sgmltag>;Frau&amp;<sgmltag>gt</sgmltag>; + &amp;<sgmltag>amp</sgmltag>; Kr&amp;<sgmltag>auml</sgmltag>;mer". + </para> + <para> + Lo interesante es usar la función <function>array_flip</function> + para cambiar la dirección de la traducción. + <informalexample> + <programlisting role="php"> +$trad = array_flip ($trad); +$original = strtr ($cad, $trad); + </programlisting> + </informalexample> + El contenido de <literal>$original</literal> sería: "Hallo &amp; + &lt;Frau> &amp; Kr&auml;mer". + <note> + <para> + Esta función fue añadida en PHP 4.0. + </para> + </note> + </para> + <para> + Vea también: <function>htmlspecialchars</function>, + <function>htmlentities</function>, <function>strtr</function>, + y <function>array_flip</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.get-meta-tags"> + <refnamediv> + <refname>get_meta_tags</refname> + <refpurpose> + Extrae todas las etiquetas meta de un archivo y retorna una matriz + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>get_meta_tags</function></funcdef> + <paramdef>string <parameter>nombrefich</parameter></paramdef> + <paramdef>int + <parameter><optional>use_ruta_include</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Abre el <parameter>nombrefich</parameter> y lo trocea línea a línea + buscando etiquetas &lt;meta> de la forma + <example> + <title>Ejemplo de Etiquetas Meta</title> + <programlisting role="html"> +&lt;meta name="autor" content="nombre"> +&lt;meta name="etiquetas" content="documentación de php3"> +&lt;/head> &lt;!-- el proceso se detiene aquí --> + </programlisting> + </example> + (preste atención a los finales de línea - el PHP utiliza una + función nativa para trocear la entrada, de modo que un archivo + de Mac no funcionará en Unix). + </para> + <para> + El valor de la propiedad name queda como clave y el valor de la + propiedad content queda como el valor de la matriz devuelta, de + modo que pueda usar fácilmente funciones estándar de matrices para + recorrerla o para acceder a valores individuales. Los caracteres + especiales en el valor de name son sustituídos por '_' y el resto + es convertido a minúsculas. + </para> + <para> + Fijando <parameter>use_ruta_include</parameter> a 1 hará que el + PHP intente abrir el archivo a través de la ruta de inclusión. + </para> + </refsect1> + </refentry> + + <refentry id="function.hebrev"> + <refnamediv> + <refname>hebrev</refname> + <refpurpose> + Convierte Hebreo lógico a texto visual + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>hebrev</function></funcdef> + <paramdef>string <parameter>texto_hebreo</parameter></paramdef> + <paramdef>int + <parameter><optional>max_cars_por_linea</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + El parámetro opcional <parameter>max_cars_por_linea</parameter> + indica el máximo número de caracteres que se emitirán por línea. + La función intenta evitar cortar palabras. + </para> + <para> + Vea también <function>hebrevc</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.hebrevc"> + <refnamediv> + <refname>hebrevc</refname> + <refpurpose> + Convierte Hebreo lógico a texto visual con conversión de saltos + de línea + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>hebrevc</function></funcdef> + <paramdef>string <parameter>texto_hebreo</parameter></paramdef> + <paramdef>int + <parameter><optional>max_cars_por_linea</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta funcion es similar a <function>hebrev</function> con la + diferencia que convierte las nuevas líneas (\n) a "&lt;br&gt;\n". + El parámetro opcional <parameter>max_cars_por_linea</parameter> + indica el máximo número de caracteres que se emitirán por línea. + La función intenta evitar cortar palabras. + </para> + <para> + Vea también <function>hebrev</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.htmlentities"> + <refnamediv> + <refname>htmlentities</refname> + <refpurpose> + Convierte todos los caracteres aplicables a entidades HTML + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>htmlentities</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función es del todo idéntica a <function>htmlspecialchars</function>, + excepto que traduce todos los caracteres que tienen equivalente + como entidad HTML. + </para> + <para> + Actualmente se utiliza el juego de caracteres ISO-8859-1. + </para> + <para> + Vea también <function>htmlspecialchars</function> y + <function>nl2br</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.htmlspecialchars"> + <refnamediv> + <refname>htmlspecialchars</refname> + <refpurpose> + Convierte caracteres especiales a entidades HTML + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>htmlspecialchars</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Ciertos caracteres tienen significados especiales en HTML, y deben + ser representados por entidades HTML si se desea preservar su + significado. Esta función devuelve una cadena con dichas conversiones + realizadas. + </para> + <simpara> + Esta función es útil para evitar que el texo entrado por el usuario + contenga marcas HTML, como ocurre en aplicaciones de foros o + libros de visita. + </simpara> + <para> + Actualmente, las traducciones hechas son: + <itemizedlist> + <listitem> + <simpara> + '&amp;' (ampersand) se convierte en '&amp;amp;' + </simpara> + </listitem> + <listitem> + <simpara> + '&quot;' (doble comilla) se convierte en '&amp;quot;' + </simpara> + </listitem> + <listitem> + <simpara> + '&lt;' (menor que) se convierte en '&amp;lt;' + </simpara> + </listitem> + <listitem> + <simpara> + '&gt;' (mayor que) se convierte en '&amp;gt;' + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + Nótese que esta función no traduce nada más que lo mostrado + más arriba. Para una traducción de entidades completa, vea + <function>htmlentities</function>. + </para> + <para> + Vea también <function>htmlentities</function> y + <function>nl2br</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.implode"> + <refnamediv> + <refname>implode</refname> + <refpurpose>Unir elementos de una matriz mediante una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>implode</function></funcdef> + <paramdef>string <parameter>cola</parameter></paramdef> + <paramdef>array <parameter>piezas</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una cadena que contiene una representación de todos los + elementos de la matriz en el mismo orden, pero con la cadena + <parameter>cola</parameter> en medio de los mismos. + <example> + <title>Ejemplo de <function>implode</function></title> + <programlisting role="php"> +$separada_dospuntos = implode (":", $matrizay); + </programlisting> + </example> + </para> + <simpara> + Vea también <function>explode</function>, <function>join</function>, + y <function>split</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.join"> + <refnamediv> + <refname>join</refname> + <refpurpose>Une elementos de una tabla mediante una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>join</function></funcdef> + <paramdef>string <parameter>cola</parameter></paramdef> + <paramdef>array <parameter>piezas</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + <function>join</function> es un alias para + <function>implode</function>, y es idéntica en todo. + </simpara> + <simpara> + Vea también <function>explode</function>, <function>implode</function>, + y <function>split</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.levenshtein"> + <refnamediv> + <refname>levenshtein</refname> + <refpurpose> + Calcula la distancia Levenshtein entre dos cadenas + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>levenshtein</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función devuelve la distancia Levenshtein entre las dos + cadenas argumento, ó -1 si alguna de las cadenas tiene más + de 255 caracteres. + </para> + <para> + La distancia Levenshtein se define como el mínimo número de + caracteres que se tienen que sustituir, insertar o borrar + para transformar <parameter>cad1</parameter> en + <parameter>cad2</parameter>. La complejidad del algoritmo es + <literal>O(m*n)</literal>, donde <literal>n</literal> y + <literal>m</literal> son las longitudes de <parameter>cad1</parameter> + y <parameter>cad2</parameter> (bastante bueno si se la compara con + <function>similar_text</function>, que es O(max(n,m)**3), pero + aún es cara). + </para> + <para> + Vea también <function>soundex</function>, + <function>similar_text</function> y + <function>metaphone</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.ltrim"> + <refnamediv> + <refname>ltrim</refname> + <refpurpose> + Elimina el espacio en blanco del principio de una cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ltrim</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función elimina el espacio en blanco del principio de una + cadena y devuelve la cadena resultante. Los caracteres de espacio + que elimina realmente son: "\n", "\r", "\t", "\v", "\0", + y el espacio en sí. + </para> + <para> + Vea también <function>chop</function> y <function>trim</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.md5"> + <refnamediv> + <refname>md5</refname> + <refpurpose>Calcula el hash md5 de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>md5</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Calcula el hash (extracto) MD5 de <parameter>cad</parameter> + usaneo el + <ulink url="&url.rfc;rfc1321.html">Algoritmo de Resumen de + Mensajes MD5 de RSA Data Security, Inc. </ulink>. + </para> + <para> + Vea también: <function>crc32</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.metaphone"> + <refnamediv> + <refname>metaphone</refname> + <refpurpose>Calcula la clave "metáfona" de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>metaphone</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Calcula la clave "metáfona" de <parameter>cad</parameter>. + </para> + <para> + Similarmente a <function>soundex</function>, metaphone crea la + misma clave para palabras que suenan parecidas. Es más precisa + que la función <function>soundex</function>, pues conoce las + reglas básicas de la pronunciación del Inglés. Las claves + metafónicas generadas son de longitud variable. + </para> + <para> + Metaphone fue desarrollado por Lawrence Philips + &lt;lphilips@verity.com>. Se describe en ["Practical + Algorithms for Programmers", Binstock &amp; Rex, Addison Wesley, + 1995]. + <note> + <para> + Esta función se añadió en PHP 4.0. + </para> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.nl2br"> + <refnamediv> + <refname>nl2br</refname> + <refpurpose>Convierte nuevas líneas a saltos de línea HTML</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>nl2br</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve la <parameter>cadena</parameter> con '&lt;BR&gt;' insertados + antes de cada nueva línea. + </para> + <para> + Vea también <function>htmlspecialchars</function>, + <function>htmlentities</function> y + <function>wordwrap</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.ord"> + <refnamediv> + <refname>ord</refname> + <refpurpose>Devuelve el valor ASCII de un caracter</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ord</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve el valor ASCII del primer caracter de + <parameter>cadena</parameter>. Esta función complementa a + <function>chr</function>. + <example> + <title>Ejemplo de <function>ord</function></title> + <programlisting role="php"> +if (ord ($cad) == 10) { + echo "El primer caracter de \$cad es un salto de línea.\n"; +} + </programlisting> + </example> + </para> + <simpara> + Vea también <function>chr</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.parse-str"> + <refnamediv> + <refname>parse_str</refname> + <refpurpose>Divide la cadena en variables</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>parse_str</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Divide <parameter>cad</parameter> como si fuera la cadena de consulta + enviada por un URL y crea las variables en el ámbito actual. + </para> + <para> + <example> + <title>Usando <function>parse_str</function></title> + <programlisting role="php"> +$cad = "primero=valor&amp;segundo[]=esto+funciona&amp;segundo[]=otro"; +parse_str($cad); +echo $primero; /* escribe "valor" */ +echo $segundo[0]; /* escribe "esto funciona" */ +echo $segundo[1]; /* escribe "otro" */ + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.print"> + <refnamediv> + <refname>print</refname> + <refpurpose>Emite una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef><function>print</function></funcdef> + <paramdef>string <parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Emite <parameter>arg</parameter>. + </simpara> + <simpara> + Vea también: <function>echo</function>, <function>printf</function>, + y <function>flush</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.printf"> + <refnamediv> + <refname>printf</refname> + <refpurpose>Emite una cadena con formato</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>printf</function></funcdef> + <paramdef>string <parameter>formato</parameter></paramdef> + <paramdef>mixed + <parameter><optional>args</optional></parameter>... + </paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Produce una salida según el <parameter>formato</parameter>, que es + descrito en la documentación para <function>sprintf</function>. + </simpara> + <simpara> + Vea también: <function>print</function>, <function>sprintf</function>, + <function>sscanf</function>, <function>fscanf</function>, + y <function>flush</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.quoted-printable-decode"> + <refnamediv> + <refname>quoted_printable_decode</refname> + <refpurpose> + Convierte una cadena con marcación imprimible a una cadena de 8 bits + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string + <function>quoted_printable_decode</function> + </funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Esta función devuelve una cadena binaria de 8 bit que se corresponde + con la cadena con marcación imprimible decodificada. Esta función es + similar a <function>imap_qprint</function>, pero sin requerir que el + módulo IMAP funcione. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.quotemeta"> + <refnamediv> + <refname>quotemeta</refname> + <refpurpose>Quote meta characters</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>quotemeta</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una versión de la cadena con una barra invertida + (<literal>\</literal>) antes de cada caracter de este + conjunto: <screen>. \\ + * ? [ ^ ] ( $ )</screen> + </para> + <simpara> + Vea también <function>addslashes</function>, + <function>htmlentities</function>, + <function>htmlspecialchars</function>, + <function>nl2br</function>, y + <function>stripslashes</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.rtrim"> + <refnamediv> + <refname>rtrim</refname> + <refpurpose>Elimina espacios en blanco al final de la cadena.</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcdef>string <function>rtrim</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcsynopsis> + <para> + Devuelve la cadena argumento sin espacios en blanco ni saltos + de línea al final. Es un alias para <function>chop</function>. + <example> + <title>Ejemplo de <function>rtrim</function></title> + <programlisting role="php"> +$recortada = rtrim ($linea); + </programlisting> + </example> + </para> + <para> + Vea también <function>trim</function>, <function>ltrim</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.sscanf"> + <refnamediv> + <refname>sscanf</refname> + <refpurpose>Trocea la entrada desde una cadena según un formato dado</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>sscanf</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>string <parameter>formato</parameter></paramdef> + <paramdef>string + <parameter><optional>var1</optional></parameter>... + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + La función<function>sscanf</function> es la función de entrada análoga + de <function>printf</function>. <function>sscanf</function> lee del + parámetro de cadena <parameter>cad</parameter> y lo interpreta según el + <parameter>formato</parameter> especificado. Si sólo se pasan dos parámetros + a esta función, los valores devueltos se harán en una matriz. + <example> + <title>Ejemplo de <function>sscanf</function></title> + <programlisting role="php"> +// obteniendo el número de serie +$numserie = sscanf("SN/2350001","SN/%d"); +// y la fecha de fabricación +$fecha = "01 Enero 2000"; +list($dia, $mes, $anno) = sscanf($fecha,"%d %s %d"); +echo "El objeto $numserie fue fabricado el: $anno-".substr($mes,0,3)."-$dia\n"; + </programlisting> + </example> + Si se pasan los parámetros opcionales, la función devolverá el número de + valores asignados. Los parámetros opcionales deben ser pasados por + referencia. + <example> + <title>Ejemplo de <function>sscanf</function> - usando parámetros opcionales</title> + <programlisting role="php"> +// obtener autor y generar la ficha DocBook +$autor = "24\tLewis Carroll"; +$n = sscanf($autor,"%d\t%s %s", &amp;$id, &amp;$nombre, &amp;$apell); +echo "&lt;autor id='$id'&gt; + &lt;firstname&gt;$nombre&lt;/firstname&gt; + &lt;surname&gt;$apell&lt;/surname&gt; +&lt;/author&gt;\n"; + </programlisting> + </example> + </para> + <para> + Vea también: <function>fscanf</function>, <function>printf</function>, + y <function>sprintf</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.setlocale"> + <refnamediv> + <refname>setlocale</refname> + <refpurpose>Fija la información de localidad</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>setlocale</function></funcdef> + <paramdef>string <parameter>categoria</parameter></paramdef> + <paramdef>string <parameter>localidad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <parameter>categoria</parameter> es una cadena que especifica + la categoría de las funciones afectadas por el ajuste de localidad: + <itemizedlist> + <listitem> + <simpara> + LC_ALL para todas las funciones + </simpara> + </listitem> + <listitem> + <simpara> + LC_COLLATE para la comparación de cadenas - aún no incluída en el PHP + </simpara> + </listitem> + <listitem> + <simpara> + LC_CTYPE para la conversión y clasificación de caracteres, como por + ejemplo <function>strtoupper</function> + </simpara> + </listitem> + <listitem> + <simpara> + LC_MONETARY para localeconv() - aún no incluída en el PHP + </simpara> + </listitem> + <listitem> + <simpara> + LC_NUMERIC para el separador decimal + </simpara> + </listitem> + <listitem> + <simpara> + LC_TIME para el formato de fecha y hora con + <function>strftime</function> + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + Si <parameter>localidad</parameter> es la cadena vacía + <literal>""</literal>, los nombres de localidad se fijarán a + partir de las variables de entorno con los mismos nombres de las + categorías anteriores, o desde "LANG". + </para> + <para> + Si la localidad es cero o <literal>"0"</literal>, el ajuste de + localidad no se ve afectado y sólo se devuelve el ajuste actual. + </para> + <para> + setlocale devuelve la nueva localidad, o &false; si la funcionalidad + de localización no está disponible en la plataforma, la localidad + especificada no existe o el nombre de categoría no es válido. + Un nombre de categoría no válido también produce un mensaje de + aviso. + </para> + </refsect1> + </refentry> + + <refentry id="function.similar-text"> + <refnamediv> + <refname>similar_text</refname> + <refpurpose> + Calcula la similitud entre dos cadenas + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>similar_text</function></funcdef> + <paramdef>string <parameter>primera</parameter></paramdef> + <paramdef>string <parameter>segunda</parameter></paramdef> + <paramdef>double + <parameter><optional>porcentaje</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función calcula la similitud entre dos cadenas según se describe + en Oliver [1993]. Nótese que esta implementación no utiliza una pila + como en el pseudo-código de Oliver, sino llamadas recursivas que pueden + o no acelerar el proceso completo. Nótese también que la complejidad + de este algoritmo es O(N**3), donde N es la longitud de la cadena + más larga. + </para> + <para> + Pasando una referencia como tercer argumento, + <function>similar_text</function> calculará para usted la similitud + como porcentaje. Devuelve el número de caracteres coincidentes en + ambas cadenas. + </para> + </refsect1> + </refentry> + + <refentry id="function.soundex"> + <refnamediv> + <refname>soundex</refname> + <refpurpose>Calcula la clave soundex de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>soundex</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Calcula la clave soundex de <parameter>cad</parameter>. + </para> + <para> + Las claves soundex tienen la propiedad de que las palabras que + se pronuncian de forma parecida tienen la misma clave, de modo + que se pueden usar para simplificar la búsqueda en las bases de + datos cuando se conoce la pronunciación pero no la transcripción. + Esta función soundex devuelve una cadena de 4 caracteres que + comienza por una letra. + </para> + <para> + Esta función soundex en particular es la descrita por Donald Knuth + en "The Art Of Computer Programming, vol. 3: Sorting And + Searching", Addison-Wesley (1973), pp. 391-392. + </para> + <para> + <example> + <title>Ejemplos de Soundex</title> + <programlisting role="php"> +soundex ("Euler") == soundex ("Ellery") == 'E460'; +soundex ("Gauss") == soundex ("Ghosh") == 'G200'; +soundex ("Knuth") == soundex ("Kant") == 'H416'; +soundex ("Lloyd") == soundex ("Ladd") == 'L300'; +soundex ("Lukasiewicz") == soundex ("Lissajous") == 'L222'; + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.sprintf"> + <refnamediv> + <refname>sprintf</refname> + <refpurpose>Devuelve una cadena con formato</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>sprintf</function></funcdef> + <paramdef>string <parameter>formato</parameter></paramdef> + <paramdef>mixed + <parameter><optional>args</optional></parameter>... + </paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Devuelve una cadena producida de acuerdo a la cadena de + <parameter>formato</parameter>. + </simpara> + <simpara> + La cadena de formato está compuesta por cero o más directivas: + caracteres ordinarios (excepto <literal>%</literal>) que son + copiados directamente al resultado, y <emphasis>especificaciones + de conversión</emphasis>, cada una de las cuales provoca la + obtención de su propio parámetro. Esto se aplica tanto a + <function>sprintf</function> como a <function>printf</function>. + </simpara> + <para> + Cada especificación de conversión consiste en uno de estos elementos, + por orden: + <orderedlist> + <listitem> + <simpara> + Un <emphasis>especificador de relleno</emphasis> opcional que + indica qué caracter se utilizará para rellenar el resultado hasta + el tamaño de cadena correcto. Este puede ser un espacio o un + <literal>0</literal> (caracter cero). El valor por defecto es + rellenar con espacios. Un caracter de relleno alternativo se puede + especificar prefijándolo con una comilla simple (<literal>'</literal>). + Vea los ejemplos más abajo. + </simpara> + </listitem> + <listitem> + <simpara> + Un <emphasis>especificador de alineación</emphasis> opcional que + indica si el resultado debe ser alineado a la izquierda o a la + derecha. Por defecto se alinea a la derecha; un caracter + <literal>-</literal> aquí lo justificará a la izquierda. + </simpara> + </listitem> + <listitem> + <simpara> + Un número opcional, un <emphasis>especificador de ancho</emphasis> + que dice el número de caracteres (mínimo) en que debería resultar + esta conversión. + </simpara> + </listitem> + <listitem> + <simpara> + Un <emphasis>especificador de precisión</emphasis> opcional que + indica cuántos dígitos decimales deben mostrarse para los números + en coma flotante. Esta opción no tienen efecto para otros tipos + que no sean double. (Otra función útil para formatear números + es <function>number_format</function>). + </simpara> + </listitem> + <listitem> + <para> + Un <emphasis>especificador de tipo</emphasis> que indica el tipo + a usar para tratar los datos de los argumentos. Los tipos posibles + son: + <simplelist> + <member> + <literal>%</literal> - un caracter literal de porcentaje. No se + precisa argumento. + </member> + <member> + <literal>b</literal> - el argumento es tratado como un entero y + presentado como un número binario. + </member> + <member> + <literal>c</literal> - el argumento es tratado como un entero, y + presentado como el caracter con dicho valor ASCII. + </member> + <member> + <literal>d</literal> - el argumento es tratado como un entero y + presentado como un número decimal. + </member> + <member> + <literal>f</literal> - el argumento es tratado como un doble y + presentado como un número de coma flotante. + </member> + <member> + <literal>o</literal> - el argumento es tratado como un entero, y + presentado como un número octal. + </member> + <member> + <literal>s</literal> - el argumento es tratado como una cadena y + es presentado como tal. + </member> + <member> + <literal>x</literal> - el argumento es tratado como un entero y + presentado como un número hexadecimal (con minúsculas). + </member> + <member> + <literal>X</literal> - el argumento es tratado como un entero y + presentado como un número hexadecimal (con mayúsculas). + </member> + </simplelist> + </para> + </listitem> + </orderedlist> + </para> + <simpara> + Vea también: <function>printf</function>, <function>sscanf</function>, + <function>fscanf</function>, y <function>number_format</function>. + </simpara> + </refsect1> + <refsect1> + <title>Ejemplos</title> + <para> + <example> + <title>Ejemplo de <function>sprintf</function>: enteros rellenos con ceros</title> + <programlisting role="php"> +$fechaiso = sprintf ("%04d-%02d-%02d", $anno, $mes, $dia); + </programlisting> + </example> + <example> + <title>Ejemplo de <function>sprintf</function>: formateando monedas</title> + <programlisting role="php"> +$pelas1 = 68.75; +$pelas2 = 54.35; +$pelas = $pelas1 + $pelas2; +// echo $pelas mostrará "123.1"; +$formateado = sprintf ("%01.2f", $pelas); +// echo $formateado mostrará "123.10" + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.strcasecmp"> + <refnamediv> + <refname>strcasecmp</refname> + <refpurpose> + Comparación de cadenas insensible a mayúsculas y minúsculas + y segura en modo binario + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strcasecmp</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve &lt; 0 si <parameter>cad1</parameter> es menor que + <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> + es mayor que <parameter>cad2</parameter>, y 0 si son iguales. + <example> + <title>Ejemplo de <function>strcasecmp</function></title> + <programlisting role="php"> +$var1 = "Hello"; +$var2 = "hello"; +if (!strcasecmp ($var1, $var2)) { + echo '$var1 es igual a $var2 en una comparación sin tener en cuenta ' + .'mayúsculas o minúsculas'; +} + </programlisting> + </example> + </para> + <simpara> + Vea también <function>ereg</function>, <function>strcmp</function>, + <function>substr</function>, <function>stristr</function>, y + <function>strstr</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.strchr"> + <refnamediv> + <refname>strchr</refname> + <refpurpose> + Encuentra la primera aparición de un caracter + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strchr</function></funcdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + <paramdef>string <parameter>aguja</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función es un alias para <function>strstr</function>, y es + idéntica en todo. + </para> + </refsect1> + </refentry> + + <refentry id="function.strcmp"> + <refnamediv> + <refname>strcmp</refname> + <refpurpose>Comparación de cadenas con seguridad binaria</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strcmp</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Devuelve &lt; 0 si <parameter>cad1</parameter> es menor que + <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> + es mayor que <parameter>cad2</parameter>, y 0 si son iguales. + </simpara> + <simpara> + Nótese que esta comparación es sensible a mayúsculas y minúsculas. + </simpara> + <simpara> + Vea también <function>ereg</function>, + <function>strcasecmp</function>, <function>substr</function>, + <function>stristr</function>, <function>strncmp</function>, + y <function>strstr</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.strcspn"> + <refnamediv> + <refname>strcspn</refname> + <refpurpose> + Encuentra la longitud del elemento inicial que no coincide + con la máscara + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strcspn</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Devuelve la longitud del segmento inicial de + <parameter>cad1</parameter> que <emphasis>no</emphasis> + contiene ninguno de los caracteres de <parameter>cad2</parameter>. + </simpara> + <simpara> + Vea también <function>strspn</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.strip-tags"> + <refnamediv> + <refname>strip_tags</refname> + <refpurpose>Elimina marcas HTML y PHP de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strip_tags</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>string + <parameter><optional>etiq_permitidas</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función intenta eliminar todas las etiquetas HTML y PHP de + la cadena dada. Causa error por precaución en caso de etiquetas + incompletas o falsas. Utiliza la misma máquina de estados para + eliminar las etiquetas que la función <function>fgetss</function>. + </para> + <para> + Puede usar el parámetro opcional para especificar las etiquetas + que no deben eliminarse. + <note> + <para> + <parameter>etiq_permitidas</parameter> fue añadido en PHP 3.0.13, + PHP4B3. + </para> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.stripcslashes"> + <refnamediv> + <refname>stripcslashes</refname> + <refpurpose> + Desmarca la cadena marcada con <function>addcslashes</function> + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>stripcslashes</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una cadena con las barras invertidas eliminadas. + Reconoce las marcas tipo C <literal>\n</literal>, + <literal>\r</literal> ..., y la representación octal y + hexadecimal. + <note> + <simpara> + Añadida en PHP4b3-dev. + </simpara> + </note> + </para> + <simpara> + Vea también <function>addcslashes</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.stripslashes"> + <refnamediv> + <refname>stripslashes</refname> + <refpurpose> + Desmarca la cadena marcada con <function>addslashes</function> + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>stripslashes</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve una cadena con las barras invertidas eliminadas + (<literal>\'</literal> se convierte en <literal>'</literal>, + etc.). Las barras invertidas dobles se convierten en sencillas. + </para> + <simpara> + Vea también <function>addslashes</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.stristr"> + <refnamediv> + <refname>stristr</refname> + <refpurpose> + <function>strstr</function> sin tener en cuenta + mayúsculas o minúsculas + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>stristr</function></funcdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + <paramdef>string <parameter>aguja</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve todo el <parameter>pajar</parameter> desde la primera + aparición de la <parameter>aguja</parameter>, siendo el + <parameter>pajar</parameter> examinado sin tener en cuenta + mayúsculas o minúsculas. + </para> + <para> + Si la <parameter>aguja</parameter> no se encuentra, devuelve + &false;. + </para> + <para> + Si la <parameter>aguja</parameter> no es una cadena, es convertida + a entero y usada como código de un carácter ASCII. + </para> + <para> + Vea también <function>strchr</function>, + <function>strrchr</function>, <function>substr</function>, y + <function>ereg</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strlen"> + <refnamediv> + <refname>strlen</refname> + <refpurpose>Obtiene la longitud de la cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strlen</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve la longitud de la <parameter>cadena</parameter>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strnatcmp"> + <refnamediv> + <refname>strnatcmp</refname> + <refpurpose> + Compara cadenas usando un algoritmo de "orden natural" + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strnatcmp</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función implementa un algoritmo de comparación que ordena + las cadenas alfanuméricas como lo haría un ser humano, que es lo + que se denomina "orden natural". A continuación se puede ver un + ejemplo de la diferencia entre este algoritmo y los algoritmos de + ordenación de cadenas habituales en los ordenadores (utilizados + en <function>strcmp</function>): + <informalexample> + <programlisting> +$matriz1 = $matriz2 = array ("img12.png","img10.png","img2.png","img1.png"); +echo "Comparación de cadenas estándar\n"; +usort($matriz1,"strcmp"); +print_r($matriz1); +echo "\nComparación de cadenas en orden natural\n"; +usort($matriz2,"strnatcmp"); +print_r($matriz2); + </programlisting> + </informalexample> + El código anterior generará la siguiente salida: + <informalexample> + <programlisting> +Comparación de cadenas estándar +Array +( + [0] =&gt; img1.png + [1] =&gt; img10.png + [2] =&gt; img12.png + [3] =&gt; img2.png +) + +Comparación de cadenas en orden natural +Array +( + [0] =&gt; img1.png + [1] =&gt; img2.png + [2] =&gt; img10.png + [3] =&gt; img12.png +) + </programlisting> + </informalexample> + Para más información, vea la página de Martin Pool sobre + <ulink url="&url.strnatcmp;">Comparación de Cadenas en + Orden Natural</ulink>. + </para> + <simpara> + De forma similar a otras funciones de comparación de cadenas, + esta devuelve &lt; 0 si <parameter>cad1</parameter> es menor que + <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> + es mayor que <parameter>cad2</parameter>, y 0 si son iguales. + </simpara> + <simpara> + Nótese que esta comparación es sensible a mayúsculas y minúsculas. + </simpara> + <simpara> + Vea también <function>ereg</function>, + <function>strcasecmp</function>, <function>substr</function>, + <function>stristr</function>, <function>strcmp</function>, + <function>strncmp</function>, <function>strnatcasecmp</function>, + y <function>strstr</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.strnatcasecmp"> + <refnamediv> + <refname>strnatcasecmp</refname> + <refpurpose> + Comparación de cadenas insensible a mayúsculas y minúsculas + usando un algoritmo de "orden natural" + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strnatcasecmp</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función implementa un algoritmo de comparación que ordena + las cadenas alfanuméricas como lo haría un ser humano. El + comportamiento de esta función es similar a + <function>strnatcmp</function>, pero la comparación no es + sensible a mayúsculas y minúsculas. Para más información, + vea la página de Martin Pool sobre + <ulink url="&url.strnatcmp;">Comparación de Cadenas en + Orden Natural</ulink>. + </para> + <simpara> + De forma similar a otras funciones de comparación de cadenas, + esta devuelve &lt; 0 si <parameter>cad1</parameter> es menor que + <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> + es mayor que <parameter>cad2</parameter>, y 0 si son iguales. + </simpara> + <simpara> + Vea también <function>ereg</function>, + <function>strcasecmp</function>, <function>substr</function>, + <function>stristr</function>, <function>strcmp</function>, + <function>strncmp</function>, <function>strnatcmp</function>, + y <function>strstr</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.strncmp"> + <refnamediv> + <refname>strncmp</refname> + <refpurpose> + Comparación de los n primeros caracteres de cadenas, con + seguridad binaria + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strncmp</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + <paramdef>int <parameter>largo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función es similar a <function>strcmp</function>, con la + diferencia que se puede especificar el (límite superior del) + número de caractares (<parameter>largo</parameter>) de cada + cadena que se usarán en la comparación. Si alguna de las cadenas + es menor que el <parameter>largo</parameter>, se usará su + longitud para la comparación. + </para> + <simpara> + + Devuelve &lt; 0 si <parameter>cad1</parameter> es menor que + <parameter>cad2</parameter>; &gt; 0 si <parameter>cad1</parameter> + es mayor que <parameter>cad2</parameter>, y 0 si son iguales. + </simpara> + <simpara> + Nótese que esta comparación es sensible a mayúsculas y minúsculas. + </simpara> + <simpara> + Vea también <function>ereg</function>, + <function>strcasecmp</function>, <function>substr</function>, + <function>stristr</function>, <function>strcmp</function>, + y <function>strstr</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.str-pad"> + <refnamediv> + <refname>str_pad</refname> + <refpurpose>Rellena una cadena con otra hasta una longitud dada</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>str_pad</function></funcdef> + <paramdef>string <parameter>entrada</parameter></paramdef> + <paramdef>int <parameter>tama_relleno</parameter></paramdef> + <paramdef>string + <parameter><optional>cad_relleno</optional></parameter></paramdef> + <paramdef>int + <parameter><optional>tipo_relleno</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función rellena la cadena <parameter>entrada</parameter> por + la derecha, la izquierda o por ambos lados hasta el largo indicado. + Si no se especifica el argumento opcional + <parameter>cad_relleno</parameter>, <parameter>entrada</parameter> + es rellenada con espacios. En caso contrario, será rellenada con + los caracteres de <parameter>cad_relleno</parameter> hasta el límite. + </para> + + <para> + El argumento opcional <parameter>tipo_relleno</parameter> puede valer + STR_PAD_RIGHT, STR_PAD_LEFT, o STR_PAD_BOTH. Si no se especifica, se + asume que vale STR_PAD_RIGHT. + </para> + + <para> + Si el valor de <parameter>tama_relleno</parameter> es negativo o menor + que la longitud de la cadena de entrada, no se produce rellenado + alguno. + </para> + + <para> + <example> + <title>Ejemplo de <function>str_pad</function></title> + <programlisting role="php"> +$entrada = "Alien"; +print str_pad($entrada, 10); // produce "Alien " +print str_pad($entrada, 10, "-=", STR_PAD_LEFT); // produce "-=-=-Alien" +print str_pad($entrada, 10, "_", STR_PAD_BOTH); // produce "__Alien___" + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.strpos"> + <refnamediv> + <refname>strpos</refname> + <refpurpose> + Encuentra la posición de la primera aparición de una cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strpos</function></funcdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + <paramdef>string <parameter>aguja</parameter></paramdef> + <paramdef>int + <parameter><optional>desplazamiento</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve la posición numérica de la primera aparición de la + <parameter>aguja</parameter> en la cadena + <parameter>pajar</parameter>. A diferencia de + <function>strrpos</function>, esta función puede tomar una + cadena completa como <parameter>aguja</parameter> y se utilizará + en su totalidad. + </para> + <para> + Si la <parameter>aguja</parameter> no es hayada, devuelve &false;. + <note> + <para> + Es fácil confundir los valores de retorno para "caracter encontrado + en la posición 0" y "caracter no encontrado". Aquí se indica cómo + detectar la diferencia: + <informalexample> + <programlisting role="php"> +// en PHP 4.0b3 y posteriores: +$pos = strpos ($micadena, "b"); +if ($pos === false) { // nota: tres signos igual + // no encontrado ... +} + +// en versiones anteriores a la 4.0b3: +$pos = strpos ($micadena, "b"); +if (is_string ($pos) &amp;&amp; !$pos) { + // no encontrado ... +} + </programlisting> + </informalexample> + </para> + </note> + </para> + <para> + Si la <parameter>aguja</parameter> no es una cadena, se convierte + a entero y se aplica como el valor ordinal de un caracter. + </para> + <para> + El parámetro opcional <parameter>desplazamiento</parameter> le permite + especificar a partir de qué caracter del <parameter>pajar</parameter> + comenzar a buscar. La posición devuelta es aún relativa al comienzo + de <parameter>pajar</parameter>. + </para> + <para> + Vea también <function>strrpos</function>, + <function>strrchr</function>, <function>substr</function>, + <function>stristr</function>, y <function>strstr</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strrchr"> + <refnamediv> + <refname>strrchr</refname> + <refpurpose> + Encuentra la última aparición de un caracter en una cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strrchr</function></funcdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + <paramdef>string <parameter>aguja</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función devuelve la porción del + <parameter>pajar</parameter> que comienza en la última aparición + de la <parameter>aguja</parameter> y continúa hasta el final + del <parameter>pajar</parameter>. + </para> + <para> + Devuelve &false; si la <parameter>aguja</parameter> no es hallada. + </para> + <para> + Si la <parameter>aguja</parameter> contiene más de un caracter, + sólo se usará el primero. + </para> + <para> + Si la <parameter>aguja</parameter> no es una cadena, se convierte + a entero y se aplica como el valor ordinal de un caracter. + <example> + <title>Ejemplo de <function>strrchr</function></title> + <programlisting role="php"> +// obtener el último directorio de $PATH +$dir = substr (strrchr ($PATH, ":"), 1); + +// obtener todo tras el último salto de línea +$texto = "Line 1\nLine 2\nLine 3"; +$apell = substr (strrchr ($texto, 10), 1 ); + </programlisting> + </example> + </para> + <para> + Vea también <function>substr</function>, + <function>stristr</function>, y <function>strstr</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.str-repeat"> + <refnamediv> + <refname>str_repeat</refname> + <refpurpose>Repite una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>str_repeat</function></funcdef> + <paramdef>string <parameter>cad_entrada</parameter></paramdef> + <paramdef>int <parameter>veces</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve la <parameter>cad_entrada</parameter> repetida + <parameter>veces</parameter>. + <parameter>veces</parameter> debe ser mayor que 0. + </para> + <example> + <title>Ejemplo de <function>str_repeat</function></title> + <programlisting role="php"> +echo str_repeat ("-=", 10); + </programlisting> + </example> + <para> + Esto mostrará "-=-=-=-=-=-=-=-=-=-=". + </para> + <note> + <para> + Esta función fue añadida en el PHP 4.0. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.strrev"> + <refnamediv> + <refname>strrev</refname> + <refpurpose>Invierte una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strrev</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuele la <parameter>cadena</parameter> invertida. + </para> + </refsect1> + </refentry> + + <refentry id="function.strrpos"> + <refnamediv> + <refname>strrpos</refname> + <refpurpose> + Encuentra la posición de la última aparición de un caracter en una cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strrpos</function></funcdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + <paramdef>char <parameter>aguja</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuele la posición numérica de la última aparición de + la <parameter>aguja</parameter> en el <parameter>pajar</parameter>. + Nótese que la aguja en este caso sólo puede ser un caracter único. + Si se pasa una cadena como aguja, sólo se utilizará el primer + caracter de la misma. + </para> + <para> + Si la <parameter>aguja</parameter> no es hayada, devuelve &false;. + </para> + <para> + Si la <parameter>aguja</parameter> no es una cadena, se convierte + a entero y se aplica como el valor ordinal de un caracter. + </para> + <para> + Vea también <function>strpos</function>, + <function>strrchr</function>, <function>substr</function>, + <function>stristr</function>, y <function>strstr</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strspn"> + <refnamediv> + <refname>strspn</refname> + <refpurpose> + Encuentra la longitud del segmento inicial que coincide con la + máscara + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>strspn</function></funcdef> + <paramdef>string <parameter>cad1</parameter></paramdef> + <paramdef>string <parameter>cad2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Devuelve la longitud del segmento inicial de + <parameter>cad1</parameter> que consiste por entero en + caracteres contenidos en <parameter>cad2</parameter>. + </simpara> + <para> + <informalexample> + <programlisting role="php"> +strspn ("42 es la respuesta. ¿Cuál es la pregunta ...?", "1234567890"); + </programlisting> + <para> + devolverá 2 como resultado. + </para> + </informalexample> + </para> + <simpara> + Vea también <function>strcspn</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.strstr"> + <refnamediv> + <refname>strstr</refname> + <refpurpose>Encuentra la primera aparición de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strstr</function></funcdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + <paramdef>string <parameter>aguja</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve todo el <parameter>pajar</parameter> desde la primera + aparición de la <parameter>aguja</parameter> hasta el final. + </para> + <para> + Si la <parameter>aguja</parameter> no es hayada, devuelve &false;. + </para> + <para> + Si la <parameter>aguja</parameter> no es una cadena, se convierte + a entero y se aplica como el valor ordinal de un caracter. + </para> + <para> + <note> + <para> + Nótese que esta función es sensible a mayúsculas y minúsculas. + Para búsquedas no sensibles, utilice <function>stristr</function>. + </para> + </note> + </para> + <para> + <example> + <title>Ejemplo de <function>strstr</function></title> + <programlisting role="php"> +$email = 'sterling@designmultimedia.com'; +$dominio = strstr ($email, '@'); +print $dominio; // imprime @designmultimedia.com + </programlisting> + </example> + </para> + <para> + Vea también <function>stristr</function>, + <function>strrchr</function>, <function>substr</function>, y + <function>ereg</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strtok"> + <refnamediv> + <refname>strtok</refname> + <refpurpose>Divide una cadena en elementos</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strtok</function></funcdef> + <paramdef>string <parameter>arg1</parameter></paramdef> + <paramdef>string <parameter>arg2</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>strtok</function> se usa para dividir en elementos una + cadena. Es decir, que si tiene una cadena como "Esta es una cadena + de ejemplo" podría dividirla en palabras individuales utilizando + el espacio como divisor. + <example> + <title>Ejemplo de <function>strtok</function></title> + <programlisting role="php"> +$cadena = "Esta es una cadena de ejemplo"; +$tok = strtok ($cadena," "); +while ($tok) { + echo "Palabra=$tok&lt;br>"; + $tok = strtok (" "); +} + </programlisting> + </example> + </para> + <para> + Nótese que sólo la primera llamada a strtok utiliza el argumento + cadena. Cada llamada subsiguiente necesita sólo el divisor a + utilizar, puesto que ella guarda la posición actual en la cadena. + Para comenzar de nuevo o para dividir otra cadena, simplemente + llame a strtok con el argumento de cadena y se inicializará. + Nótese que puede poner divisores múltiples como parámetro. La + cadena será dividida cuando alguno de los caracteres del argumento + sea hallado. + </para> + <para> + Además tenga cuidado si sus divisores valen "0", pues evalúa + como &false; en las expresiones condicionales. + </para> + <para> + Vea también <function>split</function> y + <function>explode</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strtolower"> + <refnamediv> + <refname>strtolower</refname> + <refpurpose>Pasa a minúsculas una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strtolower</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve la <parameter>cadena</parameter> con todas sus letras + en minúsculas. + </para> + <para> + Nótese que las letras son definidad por el locale actual. Esto + quiere decir que, por ejemplo, en el locale por defecto ("C"), + los caracteres como la Ñ no serán convertidos. + </para> + <example> + <title>Ejemplo de <function>strtolower</function></title> + <programlisting role="php"> +$cad = "María Tenía Un Corderito al que QUERÍA Mucho"; +$cad = strtolower($cad); +print $cad; # Visualiza maría tenía un corderito al que querÍa mucho + </programlisting> + </example> + <para> + Vea también <function>strtoupper</function> + y <function>ucfirst</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strtoupper"> + <refnamediv> + <refname>strtoupper</refname> + <refpurpose>Pasa a mayúsculas una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strtoupper</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Devuelve la <parameter>cadena</parameter> con todas sus letras + en mayúsculas. + </para> + <para> + Nótese que las letras son definidad por el locale actual. Esto + quiere decir que, por ejemplo, en el locale por defecto ("C"), + los caracteres como la ñ no serán convertidos. + </para> + <example> + <title>Ejemplo de <function>strtoupper</function></title> + <programlisting role="php"> +$cad = "María Tenía Un Corderito al que QUERÍA Mucho"; +$cad = strtoupper ($cad); +print $cad; # Visuaiza MARíA TENíA UN CORDERITO AL QUE QUERÍA MUCHO + </programlisting> + </example> + <para> + Vea también <function>strtolower</function> + and <function>ucfirst</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.str-replace"> + <refnamediv> + <refname>str_replace</refname> + <refpurpose> + Sustitiye todas las apariciones de la aguja en el pajar por la cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>str_replace</function></funcdef> + <paramdef>string <parameter>aguja</parameter></paramdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función sustituye todas las apariciones de la + <parameter>aguja</parameter> en el <parameter>pajar</parameter> + por la <parameter>cad</parameter> dada. Si no precisa reglas + especiales de sustitución, deberá usar siempre esta función en + lugar de <function>ereg_replace</function>.</para> + <para> + <example> + <title>Ejemplo de <function>str_replace</function></title> + <programlisting role="php"> +$bodytag = str_replace ("%cuerpo%", "negro", "&lt;body text=%cuerpo%>"); + </programlisting> + </example> + </para> + <para> + Esta función tiene seguridad binaria. + </para> + <note> + <para> + <function>str_replace</function> fue añadida en PHP 3.0.6, pero tuvo + errores hasta el PHP 3.0.8. + </para> + </note> + <para> + Vea también <function>ereg_replace</function> y + <function>strtr</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.strtr"> + <refnamediv> + <refname>strtr</refname> + <refpurpose>Traduce ciertos caracteres</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>strtr</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>string <parameter>desde</parameter></paramdef> + <paramdef>string <parameter>hasta</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función trabaja sobre <parameter>cad</parameter>, traduciendo + todas las apariciones de cada caracter en <parameter>desde</parameter> + por el caracter correspondiente en <parameter>hasta</parameter> y + devolviendo el resultado. + </para> + <para> + Si <parameter>desde</parameter> y <parameter>hasta</parameter> son + de distinta longitud, los caracteres extra en la más larga son + ignorados. + <example> + <title>Ejemplo de <function>strtr</function></title> + <programlisting role="php"> +$addr = strtr($addr, "äåö", "aao"); + </programlisting> + </example> + </para> + <para> + <function>strtr</function> puede llamarso sólo con dos argumentos. + Si se llama de esta manera, se comporta de otro modo: + <parameter>desde</parameter> debe ser entonces una matriz que + contenga pares cadena -> cadena que serán sustituídos en la + cadena fuente. <function>strtr</function> siempre buscará la + coincidencia más larga primero y *NO* intentará sustituir nada + en lo que haya trabajado ya. + </para> + <para> + Ejemplos: + <informalexample> + <programlisting role="php"> +$trad = array ("hola" =&gt; "hey", "hey" =&gt; "hola"); +echo strtr("hey a todos, dije hola", $trad) . "\n"; + </programlisting> + </informalexample> + Mostrará: "hola a todos, dije hey", + </para> + <note> + <simpara> + Esta característica (2 argumentos) fue añadida en el PHP 4.0 + </simpara> + </note> + <para> + Vea también <function>ereg_replace</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.substr"> + <refnamediv> + <refname>substr</refname> + <refpurpose>Devuelve parte de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>substr</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + <paramdef>int <parameter>comienzo</parameter></paramdef> + <paramdef>int + <parameter><optional>largo</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + substr devuelve la porción de <parameter>cadena</parameter> + especificada por los parámetros <parameter>comienzo</parameter> + y <parameter>largo</parameter>. + </para> + <para> + Si <parameter>comienzo</parameter> es positivo, la cadena devuelta + comenzará en dicho caracter de <parameter>cadena</parameter>. + </para> + <para> + Ejemplos: + <informalexample> + <programlisting role="php"> +$resto = substr ("abcdef", 1); // devuelve "bcdef" +$resto = substr ("abcdef", 1, 3); // devuelve "bcd" + </programlisting> + </informalexample> + </para> + <para> + Si <parameter>comienzo</parameter> es negativo, la cadena devuelta + comenzará en dicha posición desde el final de + <parameter>cadena</parameter>. + </para> + <para> + Ejemplos: + <informalexample> + <programlisting role="php"> +$resto = substr ("abcdef", -1); // devuelve "f" +$resto = substr ("abcdef", -2); // devuelve "ef" +$resto = substr ("abcdef", -3, 1); // devuelve "d" + </programlisting> + </informalexample> + </para> + <para> + Si se especifica <parameter>largo</parameter> y es positivo, la + cadena devuelta terminará <parameter>largo</parameter> caracteres + tras el <parameter>comienzo</parameter>. Si esto resulta en una + cadena con longitud negativa (porque el comienzo está pasado el + final de la cadena), la cadena devuelta contendrá únicamente el + caracter que haya en <parameter>comienzo</parameter>. + </para> + <para> + Si se especifica <parameter>largo</parameter> y es negativo, la + cadena devuelta terminará a <parameter>largo</parameter> caracteres + desde el final de <parameter>cadena</parameter>. Si esto resulta en una + cadena con longitud negativa, la cadena devuelta contendrá + únicamente el caracter que haya en <parameter>comienzo</parameter>. + </para> + <para> + Examples: + <informalexample> + <programlisting role="php"> +$resto = substr ("abcdef", 1, -1); // devuelve "bcde" + </programlisting> + </informalexample> + </para> + <para> + Vea también <function>strrchr</function> y + <function>ereg</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.substr-count"> + <refnamediv> + <refname>substr_count</refname> + <refpurpose>Cuenta el número de apariciones de la subcadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>substr_count</function></funcdef> + <paramdef>string <parameter>pajar</parameter></paramdef> + <paramdef>string <parameter>aguja</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>substr_count</function> devuelve el número de veces + que la subcadena <parameter>aguja</parameter> se encuentra en + la cadena <parameter>pajar</parameter>. + </para> + + <para> + <example> + <title>Ejemplo de <function>substr_count</function></title> + <programlisting> +print substr_count("This is a test", "is"); // prints out 2 + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.substr-replace"> + <refnamediv> + <refname>substr_replace</refname> + <refpurpose>Sustituye texto en una parte de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>substr_replace</function></funcdef> + <paramdef>string <parameter>cadena</parameter></paramdef> + <paramdef>string <parameter>sustituto</parameter></paramdef> + <paramdef>int <parameter>comienzo</parameter></paramdef> + <paramdef>int + <parameter><optional>largo</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>substr_replace</function> sustituye la parte de + <parameter>cadena</parameter> delimitada por los parámetros + <parameter>comienzo</parameter> y (opcionalmente) + <parameter>largo</parameter> por la cadena dada en + <parameter>sustituto</parameter>. Se devuelve el resultado. + </para> + <para> + Si <parameter>comienzo</parameter> es positivo, la sustitución + comenzará en dicha posición dentro de la <parameter>cadena</parameter>. + </para> + <para> + Si <parameter>comienzo</parameter> es negativo, la sustitución + comenzará en dicha posición pero contando desde el final de + <parameter>cadena</parameter>. + </para> + <para> + Si se especifica el <parameter>largo</parameter> y es positivo, + representa el largo de la porción de + <parameter>cadena</parameter> a sustituir. Si es negativo, + representa el número de caracteres desde el final de + <parameter>cadena</parameter> en los que dejar de sustituir. + Si no se especifica, valdrá por defecto + strlen(<parameter>cadena</parameter>); es decir, que acabará + la sustitución al final de <parameter>cadena</parameter>. + </para> + <para> + <example> + <title>Ejemplo de <function>substr_replace</function></title> + <programlisting role="php"> +&lt;?php +$var = 'ABCDEFGH:/MNRPQR/'; +echo "Original: $var&lt;hr&gt;\n"; + +/* Estos dos ejemplos sustituyen toda $var por 'bob'. */ +echo substr_replace ($var, 'bob', 0) . "&lt;br&gt;\n"; +echo substr_replace ($var, 'bob', 0, strlen ($var)) . "&lt;br&gt;\n"; + +/* Inserta 'bob' justo al inicio de $var. */ +echo substr_replace ($var, 'bob', 0, 0) . "&lt;br&gt;\n"; + +/* Los dos siguientes cambian 'MNRPQR' en $var por 'bob'. */ +echo substr_replace ($var, 'bob', 10, -1) . "&lt;br&gt;\n"; +echo substr_replace ($var, 'bob', -7, -1) . "&lt;br&gt;\n"; + +/* Borrar 'MNRPQR' de $var. */ +echo substr_replace ($var, '', 10, -1) . "&lt;br&gt;\n"; +?&gt; + </programlisting> + </example> + </para> + <para> + Vea también <function>str_replace</function> y + <function>substr</function>. + </para> + <note> + <simpara> + <function>substr_replace</function> fue añadida en el PHP 4.0. + </simpara> + </note> + </refsect1> + </refentry> + + <refentry id="function.trim"> + <refnamediv> + <refname>trim</refname> + <refpurpose> + Elimina espacios del principio y final de una cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>trim</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta función elimina los espacios en blanco del comienzo y del + final de una cadena y devuelve el resultado. Los caracteres de + espacio que elimina realmente son: "\n", "\r", "\t", "\v", "\0", + y el espacio en sí. + </para> + <para> + Vea también <function>chop</function> y + <function>ltrim</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.ucfirst"> + <refnamediv> + <refname>ucfirst</refname> + <refpurpose>Pasar a mayúsculas el primer caracter de una cadena</refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ucfirst</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Pone en mayúsculas el primer carácter de <parameter>cad</parameter> + si es alfabético. + </para> + <para> + Nótese que 'alfabético' está determinado por la localidad actual. + Por ejemplo, en la localidad por defecto "C", los caracteres como + la a con diéresis (ä) no serán convertidos. + <example> + <title>Ejemplo de <function>ucfirst</function></title> + <programlisting role="php"> +$texto = 'susanita tiene un ratón, un ratón chiquitín.'; +$texto = ucfirst ($texto); // $texto vale ahora: Susanita tiene un + // ratón, un ratón chiquitín. + </programlisting> + </example> + </para> + <para> + Vea también <function>strtoupper</function> y + <function>strtolower</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.ucwords"> + <refnamediv> + <refname>ucwords</refname> + <refpurpose> + Pone en mayúsculas el primer caracter de cada palabra + de una cadena + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>ucwords</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Pasa a mayúsculas la primera letra de cada palabra en + <parameter>cad</parameter> si dicho caracter es alfabético. + <example> + <title>Ejemplo de <function>ucwords</function></title> + <programlisting role="php"> +$texto = "susanita tiene un ratón, un ratón chiquitín."; +$texto = ucwords($texto); // $texto vale ahora: Susanita Tiene Un + // Ratón, Un Ratón Chiquitín. + </programlisting> + </example> + </para> + <para> + Vea también <function>strtoupper</function>, + <function>strtolower</function> y <function>ucfirst</function>. + </para> + </refsect1> + </refentry> + + + <refentry id="function.wordwrap"> + <refnamediv> + <refname>wordwrap</refname> + <refpurpose> + Corta una cadena en un número dado de caracteres usando un + caracter de ruptura de cadenas. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descripción</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>wordwrap</function></funcdef> + <paramdef>string <parameter>cad</parameter></paramdef> + <paramdef>int + <parameter><optional>ancho</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>ruptura</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Corta la cadena <parameter>cad</parameter> en la columna + especificada por el parámetro (opcional) <parameter>ancho</parameter>. + La línea se rompe utilizando el parámetro (opcional) + <parameter>ruptura</parameter>. + </para> + <para> + <function>wordwrap</function> automáticamente cortará en la + columna 75 y usará '\n' (nueva línea) si no se especifican + el <parameter>ancho</parameter> o la <parameter>ruptura</parameter>. + </para> + <para> + <example> + <title>Ejemplo de <function>wordwrap</function></title> + <programlisting role="php"> +$texto = "El veloz murciélago hindú comía feliz cardillo y kiwi."; +$textonuevo = wordwrap( $texto, 20 ); + +echo "$textonuevo\n"; + </programlisting> + </example> + </para> + <para> + Este ejemplo mostraría: + </para> + <para> + <informalexample> + <programlisting> +El veloz murciélago +hindú comía feliz cardillo y kiwi. + </programlisting> + </informalexample> + </para> + <para> + Vea también <function>nl2br</function>. + </para> + </refsect1> + </refentry> + + + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: --> Index: phpdoc/es/language/basic-syntax.xml diff -u phpdoc/es/language/basic-syntax.xml:1.1.1.1 phpdoc/es/language/basic-syntax.xml:1.2 --- phpdoc/es/language/basic-syntax.xml:1.1.1.1 Mon Aug 21 07:31:13 2000 +++ phpdoc/es/language/basic-syntax.xml Sat Jul 7 19:11:26 2001 @@ -1,124 +1,124 @@ - <chapter id="language.basic-syntax"> - <title>Sintaxis b&aacute;sica</title> - - <sect1 id="language.basic-syntax.phpmode"> - <title>Saliendo de HTML</title> - - <para> - Hay cuatro formas de salir de HTML y entrar en el "modo de c&oacute;digo - PHP":</para> - - <para> - <example> - <title>Formas de salir de HTML</title> - <programlisting> -1. &lt;? echo ("esta es la m&aacute;s simple, una instrucci&oacute;n de procesado SGML\n"); ?> - -2. &lt;?php echo("si quiere servir documentos XML, haga esto\n"); ?> - -3. &lt;script language="php"> - echo ("a algunos editores (como FrontPage) no les - gustan las intrucciones de procesado"); - &lt;/script> - -4. &lt;% echo ("Puedes tambi&eacute;n usar etiquetas tipo ASP"); %> - &lt;%= $variable; # Esto es una forma abreviada de "&lt;%echo .." %> - </programlisting> - </example></para> - - <para> - La primera forma s&oacute;lo est&aacute; disponible si se han habilitado las - etiquetas cortas. Esto se puede hacer a trav&eacute;s de la funci&oacute;n <function>short_tags</function>, - habilitando la opci&oacute;n de configuraci&oacute;n <link linkend="ini.short-open-tag">short_open_tag</link> - en el archivo de configuraci&oacute;n de PHP, o compilando PHP con la - opci&oacute;n --enable-short-tags en <command>configure</command>.</para> - - <para> - La cuarta manera est&aacute; disponible s&oacute;lo si se han habilitado las - etiquetas tipo ASP usando la opci&oacute;n de configuraci&oacute;n - <link linkend="ini.asp-tags">asp_tags</link>. - - <note> - <para>El soporte para las etiquetas tipo ASP se a&ntilde;adi&oacute; en 3.0.4.</para> - </note></para> - - <para> - La etiqueta de cierre de un bloque incluir&aacute; el car&aacute;cter de - nueva l&iacute;nea final si hay uno presente.</para></sect1> - - <sect1 id="language.basic-syntax.instruction-separation"> - <title>Separaci&oacute;n de instrucciones</title> - - <simpara> - Las instrucciones se separan igual que en C o perl - terminando - cada sentencia con un punto y coma.</simpara> - - <para> - La etiqueta de cierre (?&gt;) tambi&eacute;n implica el fin de la sentencia, as&iacute; - lo siguiente es equivalente: - - <informalexample> - <programlisting> -&lt;?php - echo "Esto es una prueba"; -?> - -&lt;?php echo "Esto es una prueba" ?> - </programlisting> - </informalexample></para></sect1> - - <sect1 id="language.basic-syntax.comments"> - <title>Comentarios</title> - - <para> - PHP soporta comentarios tipo 'C', 'C++' y shell de Unix. Por ejemplo: - - <informalexample><programlisting> -&lt;?php - echo "Esto es una prueba"; // Esto es un comentario tipo c++ para una l&iacute;nea - /* Esto es un comentario multil&iacute;nea - otra l&iacute;nea m&aacute;s de comentario*/ - echo "Esto es a&uacute;n otra prueba"; - echo "Una Prueba Final"; # Este es un comentario tipo shell -?> - </programlisting> - </informalexample></para> - - <simpara> - El tipo de comentario de "una l&iacute;nea" s&oacute;lo comenta, en realidad, - hasta el fin de la l&iacute;nea o el bloque actual de c&oacute;digo PHP, - lo que venga primero.</simpara> - <informalexample><programlisting> -&lt;h1>Esto es un &lt;?# echo "simple";?> ejemplo.&lt;/h1> -&lt;p>La cabecera de arriba dir&aacute; 'Esto es un ejemplo'. -</programlisting></informalexample> - - <simpara> - Se deber&iacute;a tener cuidado para no anidar comentarios de tipo 'C', - lo cual puede ocurrir cuando se comentan grandes bloques.</simpara> - - <informalexample><programlisting> -&lt;?php - /* - echo "Esto es una prueba"; /* Este comentario causar&aacute; un problema */ - */ -?> - </programlisting></informalexample></sect1> - </chapter> - - <!-- Keep this comment at the end of the file - Local variables: - mode: sgml - sgml-omittag:t - sgml-shorttag:t - sgml-minimize-attributes:nil - sgml-always-quote-attributes:t - sgml-indent-step:1 - sgml-indent-data:t - sgml-parent-document:nil - sgml-default-dtd-file:"../manual.ced" - sgml-exposed-tags:nil - sgml-local-catalogs:nil - sgml-local-ecat-files:nil - End: - --> + <chapter id="language.basic-syntax"> + <title>Sintaxis b&aacute;sica</title> + + <sect1 id="language.basic-syntax.phpmode"> + <title>Saliendo de HTML</title> + + <para> + Hay cuatro formas de salir de HTML y entrar en el "modo de c&oacute;digo + PHP":</para> + + <para> + <example> + <title>Formas de salir de HTML</title> + <programlisting> +1. &lt;? echo ("esta es la m&aacute;s simple, una instrucci&oacute;n de procesado SGML\n"); ?> + +2. &lt;?php echo("si quiere servir documentos XML, haga esto\n"); ?> + +3. &lt;script language="php"> + echo ("a algunos editores (como FrontPage) no les + gustan las intrucciones de procesado"); + &lt;/script> + +4. &lt;% echo ("Puedes tambi&eacute;n usar etiquetas tipo ASP"); %> + &lt;%= $variable; # Esto es una forma abreviada de "&lt;%echo .." %> + </programlisting> + </example></para> + + <para> + La primera forma s&oacute;lo est&aacute; disponible si se han habilitado las + etiquetas cortas. Esto se puede hacer a trav&eacute;s de la funci&oacute;n <function>short_tags</function>, + habilitando la opci&oacute;n de configuraci&oacute;n <link linkend="ini.short-open-tag">short_open_tag</link> + en el archivo de configuraci&oacute;n de PHP, o compilando PHP con la + opci&oacute;n --enable-short-tags en <command>configure</command>.</para> + + <para> + La cuarta manera est&aacute; disponible s&oacute;lo si se han habilitado las + etiquetas tipo ASP usando la opci&oacute;n de configuraci&oacute;n + <link linkend="ini.asp-tags">asp_tags</link>. + + <note> + <para>El soporte para las etiquetas tipo ASP se a&ntilde;adi&oacute; en 3.0.4.</para> + </note></para> + + <para> + La etiqueta de cierre de un bloque incluir&aacute; el car&aacute;cter de + nueva l&iacute;nea final si hay uno presente.</para></sect1> + + <sect1 id="language.basic-syntax.instruction-separation"> + <title>Separaci&oacute;n de instrucciones</title> + + <simpara> + Las instrucciones se separan igual que en C o perl - terminando + cada sentencia con un punto y coma.</simpara> + + <para> + La etiqueta de cierre (?&gt;) tambi&eacute;n implica el fin de la sentencia, as&iacute; + lo siguiente es equivalente: + + <informalexample> + <programlisting> +&lt;?php + echo "Esto es una prueba"; +?> + +&lt;?php echo "Esto es una prueba" ?> + </programlisting> + </informalexample></para></sect1> + + <sect1 id="language.basic-syntax.comments"> + <title>Comentarios</title> + + <para> + PHP soporta comentarios tipo 'C', 'C++' y shell de Unix. Por ejemplo: + + <informalexample><programlisting> +&lt;?php + echo "Esto es una prueba"; // Esto es un comentario tipo c++ para una l&iacute;nea + /* Esto es un comentario multil&iacute;nea + otra l&iacute;nea m&aacute;s de comentario*/ + echo "Esto es a&uacute;n otra prueba"; + echo "Una Prueba Final"; # Este es un comentario tipo shell +?> + </programlisting> + </informalexample></para> + + <simpara> + El tipo de comentario de "una l&iacute;nea" s&oacute;lo comenta, en realidad, + hasta el fin de la l&iacute;nea o el bloque actual de c&oacute;digo PHP, + lo que venga primero.</simpara> + <informalexample><programlisting> +&lt;h1>Esto es un &lt;?# echo "simple";?> ejemplo.&lt;/h1> +&lt;p>La cabecera de arriba dir&aacute; 'Esto es un ejemplo'. +</programlisting></informalexample> + + <simpara> + Se deber&iacute;a tener cuidado para no anidar comentarios de tipo 'C', + lo cual puede ocurrir cuando se comentan grandes bloques.</simpara> + + <informalexample><programlisting> +&lt;?php + /* + echo "Esto es una prueba"; /* Este comentario causar&aacute; un problema */ + */ +?> + </programlisting></informalexample></sect1> + </chapter> + + <!-- Keep this comment at the end of the file + Local variables: + mode: sgml + sgml-omittag:t + sgml-shorttag:t + sgml-minimize-attributes:nil + sgml-always-quote-attributes:t + sgml-indent-step:1 + sgml-indent-data:t + sgml-parent-document:nil + sgml-default-dtd-file:"../manual.ced" + sgml-exposed-tags:nil + sgml-local-catalogs:nil + sgml-local-ecat-files:nil + End: + --> Index: phpdoc/es/language/constants.xml diff -u phpdoc/es/language/constants.xml:1.2 phpdoc/es/language/constants.xml:1.3 --- phpdoc/es/language/constants.xml:1.2 Sat Jul 7 18:20:18 2001 +++ phpdoc/es/language/constants.xml Sat Jul 7 19:11:26 2001 @@ -1,175 +1,175 @@ - <chapter id="language.constants"> - <title>Constantes</title> - - <simpara> - PHP define varias constantes y proporciona un mecanismo para - definir m&aacute;s en tiempo de ejecuci&oacute;n. Las constantes son como las variables, - salvo por las dos circunstancias de que las constantes deben ser definidas - usando la funci&oacute;n <function>define</function>, y que no pueden ser - redefinidas m&aacute;s tarde con otro valor.</simpara> - - <para> - Las constantes predefinidas (siempre disponibles) son: - - <variablelist> - - <varlistentry> - <term>__FILE__</term> - <listitem> - <simpara> - El nombre del archivo de comandos que est&aacute; siendo interpretado - actualmente. Si se usa dentro de un archivo que ha sido incluido - o requerido, entonces se da el nombre del archivo incluido, y - no el nombre del archivo padre. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>__LINE__</term> - <listitem> - <simpara> - El n&uacute;mero de l&iacute;nea dentro del archivo que est&aacute; siendo - interpretado en la actualidad. Si se usa dentro de un - archivo incluido o requerido, entonces se da la posici&oacute;n - dentro del archivo incluido. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>PHP_VERSION</term> - <listitem> - <simpara> - La cadena que representa la versi&oacute;n del analizador de PHP - en uso en la actualidad; e.g. '3.0.8-dev'. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>PHP_OS</term> - <listitem> - <simpara> - El nombre del sistema operativo en el cu&aacute;l se ejecuta el - analizador PHP; e.g. 'Linux'. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>&true;</term> - <listitem> - <simpara> - Valor verdadero. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>&false;</term> - <listitem> - <simpara> - Valor falso. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>E_ERROR</term> - <listitem> - <simpara> - Denota un error distinto de un error de interpretaci&oacute;n - del cual no es posible recuperarse. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>E_WARNING</term> - <listitem> - <simpara> - Denota una condici&oacute;n donde PHP reconoce que hay algo err&oacute;neo, - pero continuar&aacute; de todas formas; pueden ser capturados por - el propio archivo de comandos. Un ejemplo ser&iacute;a una inv&aacute;lida - regexp en <function>ereg</function>. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>E_PARSE</term> - <listitem> - <simpara> - El interprete encontr&oacute; sintaxis inv&aacute;lida en el archivo - de comandos. La recuperaci&oacute;n no es posible. - </simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term>E_NOTICE</term> - <listitem> - <simpara> - Ocurri&oacute; algo que pudo ser o no un error. La ejecuci&oacute;n contin&uacute;a. - Los ejemplos incluyen usar una cadena sin comillas como un - &iacute;ndice "hash", o acceder a una variable que no ha sido inicializada. - </simpara> - </listitem> - </varlistentry> - </variablelist></para> - - <para> - Las constantes E_* se usan t&iacute;picamente con la funci&oacute;n - <function>error_reporting</function> para configurar el nivel - de informes de error.</para> - - <para> - Se pueden definir constantes adicionales usando la - funci&oacute;n <function>define</function>.</para> - - <para> - N&oacute;tese que son constantes, no macros tipo C; con una constante - s&oacute;lo se pueden representar datos escalares v&aacute;lidos. - - <example> - <title>Definiendo Constantes</title> - <programlisting> -&lt;?php -define("CONSTANTE", "Hola mundo."); -echo CONSTANTE; // muestra "Hola mundo." -?&gt; - </programlisting> - </example> - - <example> - <title>Usando __FILE__ y __LINE__</title> - <programlisting> -&lt;?php -function report_error($file, $line, $message) { - echo "Un error occurri&oacute; en $file en la l&iacute;nea $line: $message."; -} - -report_error(__FILE__,__LINE__, "Algo fue mal!"); -?&gt; - </programlisting> - </example></para> - - </chapter> - - <!-- Keep this comment at the end of the file - Local variables: - mode: sgml - sgml-omittag:t - sgml-shorttag:t - sgml-minimize-attributes:nil - sgml-always-quote-attributes:t - sgml-indent-step:1 - sgml-indent-data:t - sgml-parent-document:nil - sgml-default-dtd-file:"../manual.ced" - sgml-exposed-tags:nil - sgml-local-catalogs:nil - sgml-local-ecat-files:nil - End: - --> + <chapter id="language.constants"> + <title>Constantes</title> + + <simpara> + PHP define varias constantes y proporciona un mecanismo para + definir m&aacute;s en tiempo de ejecuci&oacute;n. Las constantes son como las variables, + salvo por las dos circunstancias de que las constantes deben ser definidas + usando la funci&oacute;n <function>define</function>, y que no pueden ser + redefinidas m&aacute;s tarde con otro valor.</simpara> + + <para> + Las constantes predefinidas (siempre disponibles) son: + + <variablelist> + + <varlistentry> + <term>__FILE__</term> + <listitem> + <simpara> + El nombre del archivo de comandos que est&aacute; siendo interpretado + actualmente. Si se usa dentro de un archivo que ha sido incluido + o requerido, entonces se da el nombre del archivo incluido, y + no el nombre del archivo padre. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>__LINE__</term> + <listitem> + <simpara> + El n&uacute;mero de l&iacute;nea dentro del archivo que est&aacute; siendo + interpretado en la actualidad. Si se usa dentro de un + archivo incluido o requerido, entonces se da la posici&oacute;n + dentro del archivo incluido. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>PHP_VERSION</term> + <listitem> + <simpara> + La cadena que representa la versi&oacute;n del analizador de PHP + en uso en la actualidad; e.g. '3.0.8-dev'. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>PHP_OS</term> + <listitem> + <simpara> + El nombre del sistema operativo en el cu&aacute;l se ejecuta el + analizador PHP; e.g. 'Linux'. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>&true;</term> + <listitem> + <simpara> + Valor verdadero. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>&false;</term> + <listitem> + <simpara> + Valor falso. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>E_ERROR</term> + <listitem> + <simpara> + Denota un error distinto de un error de interpretaci&oacute;n + del cual no es posible recuperarse. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>E_WARNING</term> + <listitem> + <simpara> + Denota una condici&oacute;n donde PHP reconoce que hay algo err&oacute;neo, + pero continuar&aacute; de todas formas; pueden ser capturados por + el propio archivo de comandos. Un ejemplo ser&iacute;a una inv&aacute;lida + regexp en <function>ereg</function>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>E_PARSE</term> + <listitem> + <simpara> + El interprete encontr&oacute; sintaxis inv&aacute;lida en el archivo + de comandos. La recuperaci&oacute;n no es posible. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term>E_NOTICE</term> + <listitem> + <simpara> + Ocurri&oacute; algo que pudo ser o no un error. La ejecuci&oacute;n contin&uacute;a. + Los ejemplos incluyen usar una cadena sin comillas como un + &iacute;ndice "hash", o acceder a una variable que no ha sido inicializada. + </simpara> + </listitem> + </varlistentry> + </variablelist></para> + + <para> + Las constantes E_* se usan t&iacute;picamente con la funci&oacute;n + <function>error_reporting</function> para configurar el nivel + de informes de error.</para> + + <para> + Se pueden definir constantes adicionales usando la + funci&oacute;n <function>define</function>.</para> + + <para> + N&oacute;tese que son constantes, no macros tipo C; con una constante + s&oacute;lo se pueden representar datos escalares v&aacute;lidos. + + <example> + <title>Definiendo Constantes</title> + <programlisting> +&lt;?php +define("CONSTANTE", "Hola mundo."); +echo CONSTANTE; // muestra "Hola mundo." +?&gt; + </programlisting> + </example> + + <example> + <title>Usando __FILE__ y __LINE__</title> + <programlisting> +&lt;?php +function report_error($file, $line, $message) { + echo "Un error occurri&oacute; en $file en la l&iacute;nea $line: $message."; +} + +report_error(__FILE__,__LINE__, "Algo fue mal!"); +?&gt; + </programlisting> + </example></para> + + </chapter> + + <!-- Keep this comment at the end of the file + Local variables: + mode: sgml + sgml-omittag:t + sgml-shorttag:t + sgml-minimize-attributes:nil + sgml-always-quote-attributes:t + sgml-indent-step:1 + sgml-indent-data:t + sgml-parent-document:nil + sgml-default-dtd-file:"../manual.ced" + sgml-exposed-tags:nil + sgml-local-catalogs:nil + sgml-local-ecat-files:nil + End: + --> Index: phpdoc/es/language/control-structures.xml diff -u phpdoc/es/language/control-structures.xml:1.5 phpdoc/es/language/control-structures.xml:1.6 --- phpdoc/es/language/control-structures.xml:1.5 Sat Jul 7 18:20:18 2001 +++ phpdoc/es/language/control-structures.xml Sat Jul 7 19:11:26 2001 @@ -1,1286 +1,1286 @@ - <chapter id="control-structures"> - <title>Estructuras de Control</title> - - <simpara> - Todo archivo de comandos PHP se compone de una serie de sentencias. - Una sentencia puede ser una asignaci&oacute;n, una llamada a funci&oacute;n, un bucle, - una sentencia condicional e incluso una sentencia que no haga nada - (una sentencia vac&iacute;a). Las sentencias normalmente acaban con punto y - coma. Adem&aacute;s, las sentencias se pueden agrupar en grupos de sentencias - encapsulando un grupo de sentencias con llaves. Un grupo de sentencias - es tambi&eacute;n una sentencia. En este cap&iacute;tulo se describen los diferentes - tipos de sentencias.</simpara> - - <sect1 id="control-structures.if"> - <title><literal>if</literal></title> - <para> - La construcci&oacute;n <literal>if</literal> es una de las m&aacute;s importantes - caracter&iacute;sticas de muchos lenguajes, incluido PHP. Permite la ejecuci&oacute;n - condicional de fragmentos de c&oacute;digo. PHP caracteriza una estructura - <literal>if</literal> que es similar a la de C: - <informalexample> - <programlisting> - if (expr) - sentencia - </programlisting> - </informalexample> - </para> - <simpara> - Como se describe en la secci&oacute;n sobre expresiones, expr se eval&uacute;a - a su valor condicional. Si <replaceable>expr</replaceable> - se eval&uacute;a como &true;, PHP ejecutar&aacute; la sentencia, - y si se eval&uacute;a como &false; - la ignorar&aacute;. - </simpara> - <para> - El siguiente ejemplo mostrar&iacute;a <computeroutput>a es mayor - que b</computeroutput> si <replaceable>$a</replaceable> fuera mayor - que <replaceable>$b</replaceable>: - <informalexample> - <programlisting role="php"> - if ($a > $b) - print "a es mayor que b"; - </programlisting> - </informalexample> - </para> - <para> - A menudo, se desea tener m&aacute;s de una sentencia ejecutada de forma - condicional. Por supuesto, no hay necesidad de encerrar cada sentencia - con una cl&aacute;usula <literal>if</literal>. En vez de eso, se pueden agrupar - varias sentencias en un grupo de sentencias. - Por ejemplo, este c&oacute;digo mostrar&iacute;a <computeroutput>a es mayor que - b</computeroutput> si <replaceable>$a</replaceable> fuera mayor que - <replaceable>$b</replaceable>, y entonces asignar&iacute;a el valor de - <replaceable>$a</replaceable> a <replaceable>$b</replaceable>: - <informalexample> - <programlisting role="php"> - if ($a > $b) { - print "a es mayor que b"; - $b = $a; - } - </programlisting> - </informalexample> - </para> - <simpara> - Las sentencias if se pueden anidar indefinidamente dentro de otras - sentencias <literal>if</literal>, lo cual proporciona una flexibilidad - completa para ejecuciones condicionales en las diferentes partes de - tu programa. - </simpara> - </sect1> - - <sect1 id="control-structures.else"> - <title><literal>else</literal></title> - <para> - A menudo queremos ejecutar una sentencia si se cumple una cierta - condicion, y una sentencia distinta si la condici&oacute;n no se cumple. - Esto es para lo que sirve <literal>else</literal>. - <literal>else</literal> extiende una sentencia <literal>if</literal> - para ejecutar una sentencia en caso de que la expresi&oacute;n en la sentencia - <literal>if</literal> se eval&uacute;e como &false;. Por - ejemplo, el siguiente c&oacute;digo mostrar&iacute;a <computeroutput>a es mayor que - b</computeroutput> si <replaceable>$a</replaceable> fuera mayor que - <replaceable>$b</replaceable>, y <computeroutput>a NO es mayor que b - </computeroutput> en cualquier otro caso: - <informalexample> - <programlisting role="php"> - if ($a > $b) { - print "a es mayor que b"; - } else { - print "a NO es mayor que b"; - } - </programlisting> - </informalexample> - - La sentencia <literal>else</literal> se ejecuta solamente si la - expresi&oacute;n <literal>if</literal> se eval&uacute;a como &false;, - y si hubiera alguna expresi&oacute;n <literal>elseif</literal> - s&oacute;lo si se - evaluaron tambi&eacute;n a &false; (Ver <link - linkend="control-structures.elseif">elseif</link>). - </para> - </sect1> - - <sect1 id="control-structures.elseif"> - <title><literal>elseif</literal></title> - - <para> - <literal>elseif</literal>, como su nombre sugiere, es una combinaci&oacute;n - de <literal>if</literal> y <literal>else</literal>. Como - <literal>else</literal>, extiende una sentencia <literal>if</literal> - para ejecutar una sentencia diferente en caso de que la expresi&oacute;n - <literal>if</literal> original se eval&uacute;a como &false;. - No obstante, a diferencia de <literal>else</literal>, ejecutar&aacute; - esa expresi&oacute;n alternativa solamente si la expresi&oacute;n condicional - <literal>elseif</literal> se eval&uacute;a como &true;. - Por ejemplo, el siguiente c&oacute;digo mostrar&iacute;a <computeroutput>a es - mayor que b</computeroutput>, <computeroutput>a es igual a b - </computeroutput> o <computeroutput>a es menor que b</computeroutput>: - <informalexample> - <programlisting role="php"> - if ($a > $b) { - print "a es mayor que b"; - } elseif ($a == $b) { - print "a es igual que b"; - } else { - print "a es mayor que b"; - } - </programlisting> - </informalexample> - </para> - <simpara> - Puede haber varios <literal>elseif</literal>s dentro de la misma - sentencia <literal>if</literal>. La primera expresi&oacute;n - <literal>elseif</literal> (si hay alguna) que se eval&uacute;e como - &true; se ejecutar&iacute;a. En PHP, tambi&eacute;n se puede - escribir 'else if' (con dos palabras) y el comportamiento ser&iacute;a - id&eacute;ntico al de un 'elseif' (una sola palabra). El significado - sint&aacute;ctico es ligeramente distinto (si estas familiarizado con C, - es el mismo comportamiento) pero la l&iacute;nea b&aacute;sica es que - ambos resultar&iacute;an tener exactamente el mismo comportamiento. - </simpara> - <simpara> - La sentencia <literal>elseif</literal> se ejecuta s&oacute;lo si la expresi&oacute;n - <literal>if</literal> precedente y cualquier expresi&oacute;n - <literal>elseif</literal> precedente se eval&uacute;an como - &false;, y la expresi&oacute;n - <literal>elseif</literal> actual se eval&uacute;a como &true;. - </simpara> - </sect1> - - <sect1 id="control-structures.alternative-syntax"> - <title>Sintaxis Alternativa de Estructuras de Control</title> - <para> - PHP ofrece una sintaxis altenativa para alguna de sus estructuras - de control; a saber, <literal>if</literal>, - <literal>while</literal>, <literal>for</literal>, y - <literal>switch</literal>. En cada caso, la forma b&aacute;sica de la - sintaxis alternativa es cambiar abrir-llave por dos puntos (:) y - cerrar-llave por <literal>endif;</literal>, - <literal>endwhile;</literal>, <literal>endfor;</literal>, or - <literal>endswitch;</literal>, respectivamente. - <informalexample> - <programlisting role="php"> - &lt;?php if ($a==5): ?&gt; - A es igual a 5 - &lt;?php endif; ?&gt; - </programlisting> - </informalexample> - </para> - <simpara> - En el ejemplo de arriba, el bloque HTML "A = 5" se anida dentro de una - sentencia <literal>if</literal> escrita en la sintaxis alternativa. - El bloque HTML se mostrar&iacute;a solamente si $a fuera igual a 5. - </simpara> - <para> - La sintaxis alternativa se aplica a <literal>else</literal> - y tambi&eacute;n a <literal>elseif</literal>. La siguiente es una - estructura <literal>if</literal> con <literal>elseif</literal> - y <literal>else</literal> en el formato alternativo: - <informalexample> - <programlisting role="php"> - if ($a == 5): - print "a es igual a 5"; - print "..."; - elseif ($a == 6): - print "a es igual a 6"; - print "!!!"; - else: - print "a no es ni 5 ni 6"; - endif; - </programlisting> - </informalexample> - </para> - <para> - Mirar tambi&eacute;n <link linkend="control-structures.while">while</link>, - <link linkend="control-structures.for">for</link>, e <link - linkend="control-structures.if">if</link> para m&aacute;s ejemplos. - </para> - </sect1> - - <sect1 id="control-structures.while"> - <title><literal>while</literal></title> - <para> - Los bucles <literal>while</literal> son los tipos de bucle m&aacute;s simples - en PHP. Se comportan como su contrapartida en C. La forma b&aacute;sica de - una sentencia <literal>while</literal> es: - <informalexample> - <programlisting> - while (expr) sentencia - </programlisting> - </informalexample> - </para> - <simpara> - El significado de una sentencia <literal>while</literal> es simple. - Le dice a PHP que ejecute la(s) sentencia(s) anidada(s) repetidamente, - mientras la expresi&oacute;n <literal>while</literal> se eval&uacute;e como - &true;. El valor de la expresi&oacute;n es - comprobado cada vez al principio del bucle, as&iacute; que incluso si este - valor cambia durante la ejecuci&oacute;n de la(s) sentencia(s) anidada(s), - la ejecuci&oacute;n no parar&aacute; hasta el fin de la iteraci&oacute;n (cada vez que - PHP ejecuta las sentencias en el bucle es una iteraci&oacute;n). - A veces, si la expresi&oacute;n <literal>while</literal> se eval&uacute;a como - &false; desde el principio de todo, la(s) sentencia(s) - anidada(s) no se ejecutar&aacute;n ni siquiera una vez. - </simpara> - <para> - Como con la sentencia <literal>if</literal>, se pueden agrupar - multiples sentencias dentro del mismo bucle <literal>while</literal> - encerrando un grupo de sentencias con llaves, o usando la sintaxis - alternativa: - <informalexample> - <programlisting> - while (expr): sentencia ... endwhile; - </programlisting> - </informalexample> - </para> - <para> - Los siguientes ejemplos son id&eacute;nticos, y ambos imprimen n&uacute;meros del - 1 al 10: - <informalexample> - <programlisting> - /* ejemplo 1 */ - - $i = 1; - while ($i <= 10) { - print $i++; /* el valor impreso ser&iacute;a - $i antes del incremento - (post-incremento) */ - } - - /* ejemplo 2 */ - - $i = 1; - while ($i <= 10): - print $i; - $i++; - endwhile; - </programlisting> - </informalexample> - </para> - </sect1> - - - <sect1 id="control-structures.do.while"> - <title><literal>do..while</literal></title> - - <simpara> - Los bucles <literal>do..while</literal> son muy similares a los - bucles <literal>while</literal>, excepto que las condiciones se - comprueban al final de cada iteraci&oacute;n en vez de al principio. - La principal diferencia frente a los bucles regulares - <literal>while</literal> es que se garantiza la ejecuci&oacute;n de la - primera iteraci&oacute;n de un bucle <literal>do..while</literal> - (la condici&oacute;n se comprueba s&oacute;lo al final de la iteraci&oacute;n), - mientras que puede no ser necesariamente ejecutada con un bucle - <literal>while</literal> regular (la condici&oacute;n se comprueba - al principio de cada iteraci&oacute;n, si esta se eval&uacute;a como - &false; desde el principio la ejecuci&oacute;n del bucle - finalizar&aacute; inmediatamente). - </simpara> - <para> - Hay una sola sintaxis para los bucles <literal>do..while</literal>: - - <informalexample> - <programlisting role="php"> - $i = 0; - do { - print $i; - } while ($i>0); - </programlisting> - </informalexample> - </para> - <simpara> - El bucle de arriba se ejecutar&iacute;a exactamente una sola vez, despu&eacute;s - de la primera iteraci&oacute;n, cuando la condici&oacute;n se comprueba, - se eval&uacute;a como &false; ($i no es m&aacute;s grande que 0) - y la ejecuci&oacute;n del bucle finaliza. - </simpara> - <para> - Los usuarios avanzados de C pueden estar familiarizados con un uso - distinto del bucle <literal>do..while</literal>, para permitir parar - la ejecuci&oacute;n en medio de los bloques de c&oacute;digo, encapsulandolos con - <literal>do..while</literal>(0), y usando la sentencia - <link linkend="control-structures.break"><literal>break</literal></link>. - El siguiente fragmento de c&oacute;digo demuestra esto: - <informalexample> - <programlisting role="php"> - do { - if ($i < 5) { - print "i no es lo suficientemente grande"; - break; - } - $i *= $factor; - if ($i < $minimum_limit) { - break; - } - print "i es correcto"; - ...procesa i... - } while(0); - </programlisting> - </informalexample> - </para> - <simpara> - No se preocupes si no entiende esto completamente o en absoluto. - Se pueden codificar archivos de comandos e incluso archivos de - comandos potentes sin usar esta 'propiedad'. - </simpara> - </sect1> - - <sect1 id="control-structures.for"> - <title><literal>for</literal></title> - <para> - Los bucles <literal>for</literal> son los bucles m&aacute;s complejos en - PHP. Se comportan como su contrapartida en C. La sintaxis de un - bucle <literal>for</literal> es: - <informalexample> - <programlisting> -for (expr1; expr2; expr3) sentencia - </programlisting> - </informalexample> - </para> - <simpara> - La primera expresi&oacute;n (<replaceable>expr1</replaceable>) se eval&uacute;a - (ejecuta) incondicionalmente una vez al principio del bucle. - </simpara> - <simpara> - Al comienzo de cada iteraci&oacute;n, se eval&uacute;a <replaceable>expr2 - </replaceable>. Si se eval&uacute;a como &true;, el - bucle contin&uacute;a y las sentencias anidadas se ejecutan. Si se eval&uacute;a - como &false;, la ejecuci&oacute;n del bucle finaliza. - </simpara> - <simpara> - Al final de cada iteraci&oacute;n, se eval&uacute;a (ejecuta) - <replaceable>expr3</replaceable>. - </simpara> - <simpara> - Cada una de las expresiones puede estar vac&iacute;a. - Que <replaceable>expr2</replaceable> est&eacute; vac&iacute;a significa - que el bucle deber&iacute;a correr indefinidamente (PHP implicitamente - lo considera como &true;, al igual que C). - Esto puede que no sea tan in&uacute;til como se podr&iacute;a pensar, puesto - que a menudo se quiere salir de un bucle usando una sentencia - <link linkend="control-structures.break"><literal>break</literal></link> - condicional en vez de usar la condici&oacute;n de <literal>for</literal>. - </simpara> - <para> - Considera los siguientes ejemplos. Todos ellos muestran n&uacute;meros del - 1 al 10: - - <informalexample> - <programlisting role="php"> - /* ejemplo 1 */ - - for ($i = 1; $i <= 10; $i++) { - print $i; - } - - /* ejemplo 2 */ - - for ($i = 1;;$i++) { - if ($i > 10) { - break; - } - print $i; - } - - /* ejemplo 3 */ - - $i = 1; - for (;;) { - if ($i > 10) { - break; - } - print $i; - $i++; - } - - /* ejemplo 4 */ - - for ($i = 1; $i <= 10; print $i, $i++) ; - </programlisting> - </informalexample> - </para> - <simpara> - Por supuesto, el primer ejemplo parece ser el mas elegante (o quiz&aacute;s - el cuarto), pero uno puede descubrir que ser capaz de usar expresiones - vac&iacute;as en bucles <literal>for</literal> resulta &uacute;til en muchas - ocasiones. - </simpara> - <para> - PHP tambi&eacute;n soporta la "sintaxis de dos puntos" alternativa para - bucles <literal>for</literal>. - <informalexample> - <programlisting> - for (expr1; expr2; expr3): sentencia; ...; endfor; - </programlisting> - </informalexample> - </para> - <para> - Otros lenguajes poseen una sentencia <literal>foreach</literal> para - traducir un array o una tabla hash. PHP3 no posee tal construcci&oacute;n; - PHP4 s&iacute; (ver <link linkend="control-structures.foreach">foreach</link>). - En PHP3, se puede combinar <link linkend="control-structures.while">while</link> - con las funciones <function>list</function> y <function>each</function> - para conseguir el mismo efecto. Mirar la documentaci&oacute;n de estas funciones - para ver un ejemplo. - </para> - </sect1> - - <sect1 id="control-structures.foreach"> - <title><literal>foreach</literal></title> - <para> - PHP4 (PHP3 no) incluye una construcci&oacute;n <literal>foreach</literal>, - tal como perl y algunos otros lenguajes. Esto simplemente da un - modo f&aacute;cil de iterar sobre arrays. Hay dos sintaxis; la segunda es - una extensi&oacute;n menor, pero &uacute;til de la primera: - <informalexample> - <programlisting> -foreach(expresion_array as $value) sentencia -foreach(expresion_array as $key => $value) sentencia - </programlisting> - </informalexample> - </para> - <simpara> - La primera forma recorre el array dado por - <literal>expresion_array</literal>. En cada iteraci&oacute;n, el valor del - elemento actual se asigna a <literal>$value</literal> y - el puntero interno del array se avanza en una unidad (as&iacute; en el siguiente - paso, se estar&aacute; mirando el elemento siguiente). - </simpara> - <simpara> - La segunda manera hace lo mismo, salvo que la clave del elemento - actual ser&aacute; asignada a la variable <literal>$key</literal> en cada - iteraci&oacute;n. - </simpara> - <para> - <note> - <para> - Cuando <literal>foreach</literal> comienza su primera ejecuci&oacute;n, - el puntero interno a la lista (array) se reinicia autom&aacute;ticamente al primer - elemento del array. Esto significa que no se necesita llamar a - <function>reset</function> antes de un bucle <literal>foreach</literal>. - </para> - </note> - </para> - <para> - <note> - <para> - Hay que tener en cuanta que<literal>foreach</literal> con una - copia de la lista (array) especificada y no la lista en si, por - ello el puntero de la lista no es modificado como en la construcci&oacute;n - each. - </para> - </note> - </para> - <para> - Puede haber observado que las siguientes son funcionalidades id&eacute;nticas: - <informalexample> - <programlisting role="php"> -reset( $arr ); -while( list( , $value ) = each( $arr ) ) { - echo "Valor: $value&lt;br&gt;\n"; -} - -foreach( $arr as $value ) { - echo "Valor: $value&lt;br&gt;\n"; -} - </programlisting> - </informalexample> - Las siguientes tambi&eacute;n son funcionalidades id&eacute;nticas: - <informalexample> - <programlisting role="php"> -reset( $arr ); -while( list( $key, $value ) = each( $arr ) ) { - echo "Key: $key; Valor: $value&lt;br&gt;\n"; -} - -foreach( $arr as $key => $value ) { - echo "Key: $key; Valor: $value&lt;br&gt;\n"; -} - </programlisting> - </informalexample> - </para> - <para> - Algunos ejemplos m&aacute;s para demostrar su uso: - <informalexample> - <programlisting role="php"> -/* foreach ejemplo 1: s&oacute;lo valor*/ -$a = array(1, 2, 3, 17); - -foreach($a as $v) { - print "Valor actual de \$a: $v.\n"; -} - -/* foreach ejemplo 2: valor (con clave impresa para ilustrar) */ -$a = array(1, 2, 3, 17); - -$i = 0; /* s&oacute;lo para prop&oacute;sitos demostrativos */ - -foreach($a as $v) { - print "\$a[$i] => $k.\n"; -} - -/* foreach ejemplo 3: clave y valor */ -$a = array( - "uno" => 1, - "dos" => 2, - "tres" => 3, - "diecisiete" => 17 -); - -foreach($a as $k => $v) { - print "\$a[$k] => $v.\n"; -} - </programlisting> - </informalexample> - </para> - </sect1> - - <sect1 id="control-structures.break"> - <title><literal>break</literal></title> - <simpara> - <literal>break</literal> escapa de la estructuras de control - iterante (bucle) actuales <literal>for</literal>, <literal>while</literal>, o - <literal>switch</literal>. - </simpara> - <simpara> - <literal>break</literal> accepta un par&aacute;metro opcional, el cual determina - cuantas estructuras de control hay que escapar. - </simpara> - <para> - <informalexample> - <programlisting role="php"> -$arr = array ('one', 'two', 'three', 'four', 'stop', 'five'); -while (list (, $val) = each ($arr)) { - if ($val == 'stop') { - break; /* You could also write 'break 1;' here. */ - } - echo "$val&lt;br&gt;\n"; -} - -/* Using the optional argument. */ - -$i = 0; -while (++$i) { - switch ($i) { - case 5: - echo "At 5&lt;br&gt;\n"; - break 1; /* Exit only the switch. */ - case 10: - echo "At 10; quitting&lt;br&gt;\n"; - break 2; /* Exit the switch and the while. */ - default: - break; - } -} - </programlisting> - </informalexample> - </para> - </sect1> - - <sect1 id="control-structures.continue"> - <title><literal>continue</literal></title> - - <simpara> - <literal>continue</literal> se usa dentro de la estructura del bucle - para saltar el resto de la iteraci&oacute;n actual del bucle y continuar - la ejecuci&oacute;n al comienzo de la siguiente iteraci&oacute;n. - </simpara> - <simpara> - <literal>continue</literal> accepta un par&aacute;metro opcional, el cual determina - cuantos niveles (bluces) hay que saltar antes de continuar con la ejecuci&oacute;n. - </simpara> - <para> - <informalexample> - <programlisting role="php"> - while (list($key,$value) = each($arr)) { - if ($key % 2) { // salta los miembros impares - continue; - } - do_something_odd ($value); - } -$i = 0; -while ($i++ &lt; 5) { - echo "Outer&lt;br&gt;\n"; - while (1) { - echo "&nbsp;&nbsp;Middle&lt;br&gt;\n"; - while (1) { - echo "&nbsp;&nbsp;Inner&lt;br&gt;\n"; - continue 3; - } - echo "This never gets output.&lt;br&gt;\n"; - } - echo "Neither does this.&lt;br&gt;\n"; -} - </programlisting> - </informalexample> - </para> - </sect1> - - <sect1 id="control-structures.switch"> - <title><literal>switch</literal></title> - - <simpara> - La sentencia <literal>switch</literal> es similar a una serie de - sentencias IF en la misma expresi&oacute;n. En muchas ocasiones, - se quiere comparar la misma variable (o expresi&oacute;n) con - nuchos valores diferentes, y ejecutar una parte de c&oacute;digo distinta - dependiendo de a qu&eacute; valor es igual. - Para ello sirve la sentencia <literal>switch</literal>. - </simpara> - <para> - Los siguientes dos ejemplos son dos modos distintos de escribir la - misma cosa, uno usa una serie de sentencias <literal>if</literal>, - y el otro usa la sentencia <literal>switch</literal>: - <informalexample> - <programlisting role="php"> - if ($i == 0) { - print "i es igual a 0"; - } - if ($i == 1) { - print "i es igual a 1"; - } - if ($i == 2) { - print "i es igual a 2"; - } - - switch ($i) { - case 0: - print "i es igual a 0"; - break; - case 1: - print "i es igual a 1"; - break; - case 2: - print "i es igual a 2"; - break; - } - </programlisting> - </informalexample> - </para> - <para> - Es importante entender c&oacute;mo se ejecuta la sentencia - <literal>switch</literal> para evitar errores. La - sentencia <literal>switch</literal> ejecuta l&iacute;nea por l&iacute;nea (realmente, - sentencia a sentencia). Al comienzo, no se ejecuta c&oacute;digo. - S&oacute;lo cuando se encuentra una sentencia <literal>case</literal> con un - valor que coincide con el valor de la expresi&oacute;n <literal>switch</literal> - PHP comienza a ejecutar las sentencias. PHP contin&uacute;a ejecutando las - sentencias hasta el final del bloque <literal>switch</literal>, - o la primera vez que vea una sentencia <literal>break</literal>. - Si no se escribe una sentencia <literal>break</literal> al final - de una lista de sentencias case, PHP seguir&aacute; ejecutando las sentencias - del siguiente case. Por ejemplo: - <informalexample> - <programlisting role="php"> - switch ($i) { - case 0: - print "i es igual a 0"; - case 1: - print "i es igual a 1"; - case 2: - print "i es igual a 2"; - } - </programlisting> - </informalexample> - </para> - <simpara> - Aqu&iacute;, si $i es igual a 0, ¡PHP ejecutar&iacute;a todas las sentecias print! - Si $i es igual a 1, PHP ejecutar&iacute;a las &uacute;ltimas dos sentencias print - y s&oacute;lo si $i es igual a 2, se obtendr&iacute;a la conducta 'esperada' - y solamente se mostrar&iacute;a 'i es igual a 2'. As&iacute;, es importante no - olvidar las sentencias <literal>break</literal> - (incluso aunque pueda querer evitar escribirlas intencionadamente - en ciertas circunstancias). - </simpara> - <simpara> - En una sentencia <literal>switch</literal>, la condici&oacute;n se - eval&uacute;a s&oacute;lo una vez y el resultado se compara a cada sentencia - <literal>case</literal>. En una sentencia <literal>elseif</literal>, - la condici&oacute;n se eval&uacute;a otra vez. Si tu condici&oacute;n es m&aacute;s complicada - que una comparaci&oacute;n simple y/o est&aacute; en un bucle estrecho, - un <literal>switch</literal> puede ser m&aacute;s r&aacute;pido. - </simpara> - <para> - La lista de sentencias de un case puede tambi&eacute;n estar vac&iacute;a, lo cual - simplemente pasa el control a la lista de sentencias del siguiente case. - <informalexample> - <programlisting role="php"> - switch ($i) { - case 0: - case 1: - case 2: - print "i es menor que 3, pero no negativo"; - break; - case 3: - print "i es 3"; - } - </programlisting> - </informalexample> - </para> - <para> - Un case especial es el default case. Este case coincide con - todo lo que no coincidan los otros case. Por ejemplo: - <informalexample> - <programlisting role="php"> - switch ($i) { - case 0: - print "i es igual a 0"; - break; - case 1: - print "i es igual a 1"; - break; - case 2: - print "i es igual a 2"; - break; - default: - print "i no es igual a 0, 1 o 2"; - } - </programlisting> - </informalexample> - </para> - <para> - La expresi&oacute;n <literal>case</literal> puede ser cualquier expresi&oacute;n - que se eval&uacute;e a un tipo simple, es decir, n&uacute;meros enteros o de punto - flotante y cadenas de texto. No se pueden usar aqu&iacute; ni arrays ni - objetos a menos que se conviertan a un tipo simple. - </para> - <para> - La sintaxis alternativa para las estructuras de control est&aacute; tambi&eacute;n - soportada con switch. Para m&aacute;s informaci&oacute;n, ver <link - linkend="control-structures.alternative-syntax">Sintaxis alternativa - para estructuras de control</link>. - <informalexample> - <programlisting role="php"> -switch ($i): - case 0: - print "i es igual 0"; - break; - case 1: - print "i es igual a 1"; - break; - case 2: - print "i es igual a 2"; - break; - default: - print "i no es igual a 0, 1 o 2"; - endswitch; - </programlisting> - </informalexample> - </para> - </sect1> - - <sect1 id="function.require"> - <title><function>require</function></title> - <simpara> - La sentencia <function>require</function> se sustituye a s&iacute; misma con - el archivo especificado, tal y como funciona la directiva - <literal>#include</literal> de C. - </simpara> - <simpara> - Un punto importante sobre su funcionamiento es que cuando un archivo se - incluye con <function>include</function> o se requiere con - <function>require</function>), el int&eacute;rprete sale del modo PHP - y entra en modo HTML al principio del archivo referenciado, - y vuelve de nuevo al modo PHP al final. Por esta raz&oacute;n, cualquier - c&oacute;digo dentro del archivo referenciado que debiera ser ejecutado - como c&oacute;digo PHP debe ser encerrado dentro de <link - linkend="language.basic-syntax.phpmode"> etiquetas v&aacute;lidas de - comienzo y fin de PHP</link>. - </simpara> - <simpara> - <function>require</function> no es en realidad una funci&oacute;n de PHP; - es m&aacute;s una construcci&oacute;n del lenguaje. Est&aacute; sujeta a algunas reglas - distintas de las de funciones. Por ejemplo, - <function>require</function> no esta sujeto a ninguna estructura de - control contenedora. Por otro lado, no devuelve ning&uacute;n valor; - intentar leer un valor de retorno de una llamada a un - <function>require</function> resulta en un error del int&eacute;rprete. - </simpara> - <simpara> - A diferencia de <function>include</function>, <function>require</function> - <emphasis>siempre</emphasis> leer&aacute; el archivo referenciado, - <emphasis>incluso si la l&iacute;nea en que est&aacute; no se ejecuta - nunca</emphasis>. Si se quiere incluir condicionalmente un archivo, se - usa <function>include</function>. La sentencia conditional no - afecta a <function>require</function>. No obstante, si la l&iacute;nea - en la cual aparece el <function>require</function> no se ejecuta, - tampoco se ejecutar&aacute; el c&oacute;digo del archivo referenciado. - </simpara> - <simpara> - De forma similar, las estructuras de bucle no afectan la conducta de - <function>require</function>. Aunque el c&oacute;digo contenido en el - archivo referenciado est&aacute; todav&iacute;a sujeto al bucle, el propio - <function>require</function> s&oacute;lo ocurre una vez. - </simpara> - <para> - Esto significa que no se puede poner una sentencia - <function>require</function> dentro de una estructura de bucle y - esperar que incluya el contenido de un archivo distinto en cada - iteraci&oacute;n. Para hacer esto, usa una sentencia - <function>include</function>. - <informalexample> - <programlisting role="php"> -require( 'header.inc' ); - </programlisting> - </informalexample> - </para> - <simpara> - When a file is <function>require</function>ed, the code it - contains inherits the variable scope of the line on which the - <function>require</function> occurs. Any variables available at - that line in the calling file will be available within the called - file. If the <function>require</function> occurs inside a - function within the calling file, then all of the code contained - in the called file will behave as though it had been defined - inside that function. - </simpara> - <para> - If the <function>require</function>ed file is called via HTTP - using the fopen wrappers, and if the target server interprets the - target file as PHP code, variables may be passed to the - <function>require</function>ed file using an URL request string as - used with HTTP GET. This is not strictly speaking the same thing - as <function>require</function>ing the file and having it inherit - the parent file's variable scope; the script is actually being run - on the remote server and the result is then being included into - the local script. - <informalexample> - <programlisting role="php"> -/* This example assumes that someserver is configured to parse .php - * files and not .txt files. Also, 'works' here means that the variables - * $varone and $vartwo are available within the require()ed file. */ - -/* Won't work; file.txt wasn't handled by someserver. */ -require ("http://someserver/file.txt?varone=1&amp;vartwo=2"); - -/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2' - * on the local filesystem. */ -require ("file.php?varone=1&amp;vartwo=2"); - -/* Works. */ -require ("http://someserver/file.php?varone=1&amp;vartwo=2"); - -$varone = 1; -$vartwo = 2; -require ("file.txt"); /* Works. */ -require ("file.php"); /* Works. */ - </programlisting> - </informalexample> - </para> - <simpara> - En PHP3, es posible ejecutar una sentencia <literal>return</literal> - dentro de un archivo referenciado con <function>require</function>, - en tanto en cuanto esa sentencia aparezca en el &aacute;mbito global del - archivo requerido (<function>require</function>). No puede aparecer - dentro de ning&uacute;n bloque (lo que siginifica dentro de llaves({})). - En PHP4, no obstante, esta capacidad ha sido desestimada. - Si se necesita esta funcionalidad, v&eacute;ase <function>include</function>. - </simpara> - <simpara> - Ver tambien <function>include</function>, <function>require_once</function>, - <function>include_once</function>, <function>readfile</function>, - y <function>virtual</function>. - </simpara> - </sect1> - - <sect1 id="function.include"> - <title><function>include</function></title> - <simpara> - La sentencia <function>include</function> incluye y eval&uacute;a - el archivo especificado. - </simpara> - <simpara> - Si "URL fopen wrappers" esta activada en PHP (como est&aacute; en la - configuraci&oacute;n inicial), se puede especificar el fichero que se - va a incluir usando una URL en vez de un fichero local (con su Path) - Ver <link linkend="features.remote-files">Ficheros remotos</link> - y <function>fopen</function> para m&aacute;s informaci&oacute;n. - </simpara> - <simpara> - Un punto importante sobre su funcionamiento es que cuando un archivo - se incluye con <function>include</function> o se requiere con - <function>require</function>, el int&eacute;rprete sale del modo PHP - y entra en modo HTML al principio del archivo referenciado, - y vuelve de nuevo al modo PHP al final. Por esta raz&oacute;n, cualquier - c&oacute;digo dentro del archivo referenciado que debiera ser ejecutado - como c&oacute;digo PHP debe ser encerrado dentro de <link - linkend="language.basic-syntax.phpmode"> etiquetas v&aacute;lidas de - comienzo y fin de PHP</link>. - </simpara> - <para> - Esto sucede cada vez que se encuentra la sentencia - <function>include</function>, as&iacute; que se puede usar una sentencia - <function>include</function> dentro de una estructura de bucle para - incluir un n&uacute;mero de archivos diferentes. - - <informalexample> - <programlisting role="php"> -$archivos = array ('primero.inc', 'segundo.inc', 'tercero.inc'); -for ($i = 0; $i < count($archivos); $i++) { - include $archivos[$i]; -} - </programlisting> - </informalexample> - </para> - <para> - <function>include</function> difiere de - <function>require</function> en que la sentencia include se - re-eval&uacute;a cada vez que se encuentra (y s&oacute;lo cuando est&aacute; siendo - ejecutada), mientras que la sentencia <function>require</function> - se reemplaza por el archivo referenciado cuando se encuentra por - primera vez, se vaya a evaluar el contenido del archivo o no - (por ejemplo, si est&aacute; dentro de una sentencia <link - linkend="control-structures.if">if</link> cuya condici&oacute;n evaluada - es falsa). - </para> - <para> - Debido a que <function>include</function> es una construcci&oacute;n especial - del lenguaje, se debe encerrar dentro de un bloque de sentencias si - est&aacute; dentro de un bloque condicional. - <informalexample> - <programlisting role="php"> - /* Esto es ERR&Oacute;NEO y no funcionar&aacute; como se desea. */ - - if ($condicion) - include($archivo); - else - include($otro); - - /* Esto es CORRECTO. */ - - if ($condicion) { - include($archivo); - } else { - include($otro); - } - </programlisting> - </informalexample> - </para> - <simpara> - En ambos, PHP3 y PHP4, es posible ejecutar una sentencia - <literal>return</literal> dentro de un archivo incluido con - <function>include</function>, para terminar el procesado de ese - archivo y volver al archivo de comandos que lo llam&oacute;. - Existen algunas diferencias en el modo en que esto funciona, - no obstante. La primera es que en PHP3, <literal>return</literal> - no puede aparecer dentro de un bloque a menos que sea un bloque de - funci&oacute;n, en el cual <literal>return</literal> se aplica a esa funci&oacute;n - y no al archivo completo. En PHP4, no obstante, esta restricci&oacute;n no - existe. Tambi&eacute;n, PHP4 permite devolver valores desde archivos - incluidos con <function>include</function>. Se puede capturar el valor de la - llamada a <function>include</function> como se har&iacute;a con una - funci&oacute;n normal. Esto genera un error de int&eacute;rprete en PHP3. - </simpara> - <example> - <title><function>include</function> en PHP3 y PHP4</title> - <para> - Asumamos la existencia del siguiente archivo (llamado - <filename>test.inc</filename>) en el mismo directorio que el - archivo principal: - <programlisting role="php"> -&lt?php -echo "Antes del return &lt;br&gt;\n"; -if ( 1 ) { - return 27; -} -echo "Despu&eacute;s del return &lt;br&gt;\n"; -?&gt; - </programlisting> - </para> - <para> - Asumamos que el archivo principal (<filename>main.html</filename>) - contiene lo siguiente: - <programlisting role="php"> -&lt?php -$retval = include( 'test.inc' ); -echo "El archivo devolvi&oacute;: '$retval'&lt;br&gt;\n"; -?&gt; - </programlisting> - </para> - <para> - Cuando se llama a <filename>main.html</filename> en PHP3, - generar&aacute; un error del int&eacute;rprete en la linea 2; no se puede - capturar el valor de un <function>include</function> en PHP3. - En PHP4, no obstante, el resultado ser&aacute;: - <screen> -Antes del return -El archivo devolvi&oacute;: '27' - </screen> - </para> - <para> - Ahora, asumamos que se ha modificado <filename>main.html</filename> - para que contenga lo siguiente: - <programlisting role="php"> -&lt?php -include( 'test.inc' ); -echo "De vuelta en main.html&lt;br&gt;\n"; -?&gt; - </programlisting> - </para> - <para> - En PHP4, la salida ser&aacute;: - <screen> -Antes del return -De vuelta en main.html - </screen> - No obstante, PHP3 dar&aacute; la siguiente salida: - <screen> -Antes del return -27De vuelta en main.html - -Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5 - </screen> - </para> - <para> - El error del int&eacute;rprete es resultado del hecho de que la sentencia - <literal>return</literal> est&aacute; encerrada en un bloque de no-funci&oacute;n - dentro de <filename>test.inc</filename>. Cuando el return se mueve - fuera del bloque, la salida es: - <screen> -Antes del return -27De vuelta en main.html - </screen> - </para> - <para> - El '27' esp&uacute;reo se debe al hecho de que PHP3 no soporta devolver - valores con <literal>return</literal> desde archivos como ese. - </para> - </example> - <simpara> - When a file is <function>include</function>ed, the code it - contains inherits the variable scope of the line on which the - <function>include</function> occurs. Any variables available at - that line in the calling file will be available within the called - file. If the <function>include</function> occurs inside a - function within the calling file, then all of the code contained - in the called file will behave as though it had been defined - inside that function. - </simpara> - <para> - If the <function>include</function>ed file is called via HTTP - using the fopen wrappers, and if the target server interprets the - target file as PHP code, variables may be passed to the - <function>include</function>ed file using an URL request string as - used with HTTP GET. This is not strictly speaking the same thing - as <function>include</function>ing the file and having it inherit - the parent file's variable scope; the script is actually being run - on the remote server and the result is then being included into - the local script. - <informalexample> - <programlisting role="php"> -/* This example assumes that someserver is configured to parse .php - * files and not .txt files. Also, 'works' here means that the variables - * $varone and $vartwo are available within the include()ed file. */ - -/* Won't work; file.txt wasn't handled by someserver. */ -include ("http://someserver/file.txt?varone=1&amp;vartwo=2"); - -/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2' - * on the local filesystem. */ -include ("file.php?varone=1&amp;vartwo=2"); - -/* Works. */ -include ("http://someserver/file.php?varone=1&amp;vartwo=2"); - -$varone = 1; -$vartwo = 2; -include ("file.txt"); /* Works. */ -include ("file.php"); /* Works. */ - </programlisting> - </informalexample> - </para> - <simpara> - See also <function>require</function>, <function>require_once</function>, - <function>include_once</function>, <function>readfile</function>, - and <function>virtual</function>. - </simpara> - </sect1> - - <sect1 id="function.require-once"> - <title><function>require_once</function></title> - <para> - The <function>require_once</function> statement replaces - itself with the specified file, much like the C preprocessor's - <literal>#include</literal> works, and in that respect is - similar to the <function>require</function> statement. The main - difference is that in an inclusion chain, the use of - <function>require_once</function> will assure that the code is - added to your script only once, and avoid clashes with variable - values or function names that can happen. - </para> - <para> - For example, if you create the following 2 include files - <literal>utils.inc</literal> and <literal>foolib.inc</literal> - <example> - <title>utils.inc</title> - <programlisting role="php"> -&lt;?php -define(PHPVERSION, floor(phpversion())); -echo "GLOBALS ARE NICE\n"; -function goodTea() { - return "Oolong tea tastes good!"; -} -?&gt; - </programlisting> - </example> - <example> - <title>foolib.inc</title> - <programlisting role="php"> -&lt;?php -require ("utils.inc"); -function showVar($var) { - if (PHPVERSION == 4) { - print_r($var); - } else { - dump_var($var); - } -} - -// bunch of other functions ... -?&gt; - </programlisting> - </example> - And then you write a script <literal>cause_error_require.php</literal> - <example> - <title>cause_error_require.php</title> - <programlisting role="php"> -&lt;?php -require("foolib.inc"); -/* the following will generate an error */ -require("utils.inc"); -$foo = array("1",array("complex","quaternion")); -echo "this is requiring utils.inc again which is also\n"; -echo "required in foolib.inc\n"; -echo "Running goodTea: ".goodTea()."\n"; -echo "Printing foo: \n"; -showVar($foo); -?&gt; - </programlisting> - </example> - When you try running the latter one, the resulting ouptut will be (using - PHP 4.01pl2): - <informalexample> - <programlisting> -GLOBALS ARE NICE -GLOBALS ARE NICE - -Fatal error: Cannot redeclare causeerror() in utils.inc on line 5 - </programlisting> - </informalexample> - By modifying <literal>foolib.inc</literal> and - <literal>cause_errror_require.php</literal> - to use <function>require_once</function> - instead of <function>require</function> and renaming the - last one to <literal>avoid_error_require_once.php</literal>, we have: - <example> - <title>foolib.inc (fixed)</title> - <programlisting role="php"> -... -require_once("utils.inc"); -function showVar($var) { -... - </programlisting> - </example> - <example> - <title>avoid_error_require_once.php</title> - <programlisting role="php"> -... -require_once("foolib.inc"); -require_once("utils.inc"); -$foo = array("1",array("complex","quaternion")); -... - </programlisting> - </example> - And when running the latter, the output will be (using PHP 4.0.1pl2): - <informalexample> - <programlisting> -GLOBALS ARE NICE -this is requiring globals.inc again which is also -required in foolib.inc -Running goodTea: Oolong tea tastes good! -Printing foo: -Array -( - [0] =&gt; 1 - [1] =&gt; Array - ( - [0] =&gt; complex - [1] =&gt; quaternion - ) - -) - </programlisting> - </informalexample> - </para> - <para> - Also note that, analogous to the behavior of the - <literal>#include</literal> of the C preprocessor, this statement - acts at "compile time", e.g. when the script is parsed and before it - is executed, and should not be used for parts of the script that need - to be inserted dynamically during its execution. You should use - <function>include_once</function> or <function>include</function> - for that purpose. - </para> - <para> - For more examples on using <function>require_once</function> and - <function>include_once</function>, look at the PEAR code included in - the latest PHP source code distributions. - </para> - <para> - See also: <function>require</function>, - <function>include</function>, <function>include_once</function>, - <function>get_required_files</function>, - <function>get_included_files</function>, <function>readfile</function>, - and <function>virtual</function>. - </para> - </sect1> - - <sect1 id="function.include-once"> - <title><function>include_once</function></title> - <para> - The <function>include_once</function> statement includes and evaluates - the specified file during the execution of the script. - This is a behavior similar to the <function>include</function> statement, - with the important difference that if the code from a file has already - been included, it will not be included again. - </para> - <para> - As mentioned in the <function>require_once</function> description, the - <function>include_once</function> should be used in the cases in which - the same file might be included and evaluated more than once during a - particular execution of a script, and you want to be sure that it is - included exactly once to avoid problems with function redefinitions, - variable value reassignments, etc. - </para> - <para> - For more examples on using <function>require_once</function> and - <function>include_once</function>, look at the PEAR code included in - the latest PHP source code distributions. - </para> - <para> - See also: <function>require</function>, - <function>include</function>, <function>require_once</function>, - <function>get_required_files</function>, - <function>get_included_files</function>, <function>readfile</function>, - and <function>virtual</function>. - </para> - </sect1> - - </chapter> - - <!-- Keep this comment at the end of the file - Local variables: - mode: sgml - sgml-omittag:t - sgml-shorttag:t - sgml-minimize-attributes:nil - sgml-always-quote-attributes:t - sgml-indent-step:1 - sgml-indent-data:t - sgml-parent-document:nil - sgml-default-dtd-file:"../../manual.ced" - sgml-exposed-tags:nil - sgml-local-catalogs:nil - sgml-local-ecat-files:nil - End: - --> + <chapter id="control-structures"> + <title>Estructuras de Control</title> + + <simpara> + Todo archivo de comandos PHP se compone de una serie de sentencias. + Una sentencia puede ser una asignaci&oacute;n, una llamada a funci&oacute;n, un bucle, + una sentencia condicional e incluso una sentencia que no haga nada + (una sentencia vac&iacute;a). Las sentencias normalmente acaban con punto y + coma. Adem&aacute;s, las sentencias se pueden agrupar en grupos de sentencias + encapsulando un grupo de sentencias con llaves. Un grupo de sentencias + es tambi&eacute;n una sentencia. En este cap&iacute;tulo se describen los diferentes + tipos de sentencias.</simpara> + + <sect1 id="control-structures.if"> + <title><literal>if</literal></title> + <para> + La construcci&oacute;n <literal>if</literal> es una de las m&aacute;s importantes + caracter&iacute;sticas de muchos lenguajes, incluido PHP. Permite la ejecuci&oacute;n + condicional de fragmentos de c&oacute;digo. PHP caracteriza una estructura + <literal>if</literal> que es similar a la de C: + <informalexample> + <programlisting> + if (expr) + sentencia + </programlisting> + </informalexample> + </para> + <simpara> + Como se describe en la secci&oacute;n sobre expresiones, expr se eval&uacute;a + a su valor condicional. Si <replaceable>expr</replaceable> + se eval&uacute;a como &true;, PHP ejecutar&aacute; la sentencia, + y si se eval&uacute;a como &false; - la ignorar&aacute;. + </simpara> + <para> + El siguiente ejemplo mostrar&iacute;a <computeroutput>a es mayor + que b</computeroutput> si <replaceable>$a</replaceable> fuera mayor + que <replaceable>$b</replaceable>: + <informalexample> + <programlisting role="php"> + if ($a > $b) + print "a es mayor que b"; + </programlisting> + </informalexample> + </para> + <para> + A menudo, se desea tener m&aacute;s de una sentencia ejecutada de forma + condicional. Por supuesto, no hay necesidad de encerrar cada sentencia + con una cl&aacute;usula <literal>if</literal>. En vez de eso, se pueden agrupar + varias sentencias en un grupo de sentencias. + Por ejemplo, este c&oacute;digo mostrar&iacute;a <computeroutput>a es mayor que + b</computeroutput> si <replaceable>$a</replaceable> fuera mayor que + <replaceable>$b</replaceable>, y entonces asignar&iacute;a el valor de + <replaceable>$a</replaceable> a <replaceable>$b</replaceable>: + <informalexample> + <programlisting role="php"> + if ($a > $b) { + print "a es mayor que b"; + $b = $a; + } + </programlisting> + </informalexample> + </para> + <simpara> + Las sentencias if se pueden anidar indefinidamente dentro de otras + sentencias <literal>if</literal>, lo cual proporciona una flexibilidad + completa para ejecuciones condicionales en las diferentes partes de + tu programa. + </simpara> + </sect1> + + <sect1 id="control-structures.else"> + <title><literal>else</literal></title> + <para> + A menudo queremos ejecutar una sentencia si se cumple una cierta + condicion, y una sentencia distinta si la condici&oacute;n no se cumple. + Esto es para lo que sirve <literal>else</literal>. + <literal>else</literal> extiende una sentencia <literal>if</literal> + para ejecutar una sentencia en caso de que la expresi&oacute;n en la sentencia + <literal>if</literal> se eval&uacute;e como &false;. Por + ejemplo, el siguiente c&oacute;digo mostrar&iacute;a <computeroutput>a es mayor que + b</computeroutput> si <replaceable>$a</replaceable> fuera mayor que + <replaceable>$b</replaceable>, y <computeroutput>a NO es mayor que b + </computeroutput> en cualquier otro caso: + <informalexample> + <programlisting role="php"> + if ($a > $b) { + print "a es mayor que b"; + } else { + print "a NO es mayor que b"; + } + </programlisting> + </informalexample> + + La sentencia <literal>else</literal> se ejecuta solamente si la + expresi&oacute;n <literal>if</literal> se eval&uacute;a como &false;, + y si hubiera alguna expresi&oacute;n <literal>elseif</literal> - s&oacute;lo si se + evaluaron tambi&eacute;n a &false; (Ver <link + linkend="control-structures.elseif">elseif</link>). + </para> + </sect1> + + <sect1 id="control-structures.elseif"> + <title><literal>elseif</literal></title> + + <para> + <literal>elseif</literal>, como su nombre sugiere, es una combinaci&oacute;n + de <literal>if</literal> y <literal>else</literal>. Como + <literal>else</literal>, extiende una sentencia <literal>if</literal> + para ejecutar una sentencia diferente en caso de que la expresi&oacute;n + <literal>if</literal> original se eval&uacute;a como &false;. + No obstante, a diferencia de <literal>else</literal>, ejecutar&aacute; + esa expresi&oacute;n alternativa solamente si la expresi&oacute;n condicional + <literal>elseif</literal> se eval&uacute;a como &true;. + Por ejemplo, el siguiente c&oacute;digo mostrar&iacute;a <computeroutput>a es + mayor que b</computeroutput>, <computeroutput>a es igual a b + </computeroutput> o <computeroutput>a es menor que b</computeroutput>: + <informalexample> + <programlisting role="php"> + if ($a > $b) { + print "a es mayor que b"; + } elseif ($a == $b) { + print "a es igual que b"; + } else { + print "a es mayor que b"; + } + </programlisting> + </informalexample> + </para> + <simpara> + Puede haber varios <literal>elseif</literal>s dentro de la misma + sentencia <literal>if</literal>. La primera expresi&oacute;n + <literal>elseif</literal> (si hay alguna) que se eval&uacute;e como + &true; se ejecutar&iacute;a. En PHP, tambi&eacute;n se puede + escribir 'else if' (con dos palabras) y el comportamiento ser&iacute;a + id&eacute;ntico al de un 'elseif' (una sola palabra). El significado + sint&aacute;ctico es ligeramente distinto (si estas familiarizado con C, + es el mismo comportamiento) pero la l&iacute;nea b&aacute;sica es que + ambos resultar&iacute;an tener exactamente el mismo comportamiento. + </simpara> + <simpara> + La sentencia <literal>elseif</literal> se ejecuta s&oacute;lo si la expresi&oacute;n + <literal>if</literal> precedente y cualquier expresi&oacute;n + <literal>elseif</literal> precedente se eval&uacute;an como + &false;, y la expresi&oacute;n + <literal>elseif</literal> actual se eval&uacute;a como &true;. + </simpara> + </sect1> + + <sect1 id="control-structures.alternative-syntax"> + <title>Sintaxis Alternativa de Estructuras de Control</title> + <para> + PHP ofrece una sintaxis altenativa para alguna de sus estructuras + de control; a saber, <literal>if</literal>, + <literal>while</literal>, <literal>for</literal>, y + <literal>switch</literal>. En cada caso, la forma b&aacute;sica de la + sintaxis alternativa es cambiar abrir-llave por dos puntos (:) y + cerrar-llave por <literal>endif;</literal>, + <literal>endwhile;</literal>, <literal>endfor;</literal>, or + <literal>endswitch;</literal>, respectivamente. + <informalexample> + <programlisting role="php"> + &lt;?php if ($a==5): ?&gt; + A es igual a 5 + &lt;?php endif; ?&gt; + </programlisting> + </informalexample> + </para> + <simpara> + En el ejemplo de arriba, el bloque HTML "A = 5" se anida dentro de una + sentencia <literal>if</literal> escrita en la sintaxis alternativa. + El bloque HTML se mostrar&iacute;a solamente si $a fuera igual a 5. + </simpara> + <para> + La sintaxis alternativa se aplica a <literal>else</literal> + y tambi&eacute;n a <literal>elseif</literal>. La siguiente es una + estructura <literal>if</literal> con <literal>elseif</literal> + y <literal>else</literal> en el formato alternativo: + <informalexample> + <programlisting role="php"> + if ($a == 5): + print "a es igual a 5"; + print "..."; + elseif ($a == 6): + print "a es igual a 6"; + print "!!!"; + else: + print "a no es ni 5 ni 6"; + endif; + </programlisting> + </informalexample> + </para> + <para> + Mirar tambi&eacute;n <link linkend="control-structures.while">while</link>, + <link linkend="control-structures.for">for</link>, e <link + linkend="control-structures.if">if</link> para m&aacute;s ejemplos. + </para> + </sect1> + + <sect1 id="control-structures.while"> + <title><literal>while</literal></title> + <para> + Los bucles <literal>while</literal> son los tipos de bucle m&aacute;s simples + en PHP. Se comportan como su contrapartida en C. La forma b&aacute;sica de + una sentencia <literal>while</literal> es: + <informalexample> + <programlisting> + while (expr) sentencia + </programlisting> + </informalexample> + </para> + <simpara> + El significado de una sentencia <literal>while</literal> es simple. + Le dice a PHP que ejecute la(s) sentencia(s) anidada(s) repetidamente, + mientras la expresi&oacute;n <literal>while</literal> se eval&uacute;e como + &true;. El valor de la expresi&oacute;n es + comprobado cada vez al principio del bucle, as&iacute; que incluso si este + valor cambia durante la ejecuci&oacute;n de la(s) sentencia(s) anidada(s), + la ejecuci&oacute;n no parar&aacute; hasta el fin de la iteraci&oacute;n (cada vez que + PHP ejecuta las sentencias en el bucle es una iteraci&oacute;n). + A veces, si la expresi&oacute;n <literal>while</literal> se eval&uacute;a como + &false; desde el principio de todo, la(s) sentencia(s) + anidada(s) no se ejecutar&aacute;n ni siquiera una vez. + </simpara> + <para> + Como con la sentencia <literal>if</literal>, se pueden agrupar + multiples sentencias dentro del mismo bucle <literal>while</literal> + encerrando un grupo de sentencias con llaves, o usando la sintaxis + alternativa: + <informalexample> + <programlisting> + while (expr): sentencia ... endwhile; + </programlisting> + </informalexample> + </para> + <para> + Los siguientes ejemplos son id&eacute;nticos, y ambos imprimen n&uacute;meros del + 1 al 10: + <informalexample> + <programlisting> + /* ejemplo 1 */ + + $i = 1; + while ($i <= 10) { + print $i++; /* el valor impreso ser&iacute;a + $i antes del incremento + (post-incremento) */ + } + + /* ejemplo 2 */ + + $i = 1; + while ($i <= 10): + print $i; + $i++; + endwhile; + </programlisting> + </informalexample> + </para> + </sect1> + + + <sect1 id="control-structures.do.while"> + <title><literal>do..while</literal></title> + + <simpara> + Los bucles <literal>do..while</literal> son muy similares a los + bucles <literal>while</literal>, excepto que las condiciones se + comprueban al final de cada iteraci&oacute;n en vez de al principio. + La principal diferencia frente a los bucles regulares + <literal>while</literal> es que se garantiza la ejecuci&oacute;n de la + primera iteraci&oacute;n de un bucle <literal>do..while</literal> + (la condici&oacute;n se comprueba s&oacute;lo al final de la iteraci&oacute;n), + mientras que puede no ser necesariamente ejecutada con un bucle + <literal>while</literal> regular (la condici&oacute;n se comprueba + al principio de cada iteraci&oacute;n, si esta se eval&uacute;a como + &false; desde el principio la ejecuci&oacute;n del bucle + finalizar&aacute; inmediatamente). + </simpara> + <para> + Hay una sola sintaxis para los bucles <literal>do..while</literal>: + + <informalexample> + <programlisting role="php"> + $i = 0; + do { + print $i; + } while ($i>0); + </programlisting> + </informalexample> + </para> + <simpara> + El bucle de arriba se ejecutar&iacute;a exactamente una sola vez, despu&eacute;s + de la primera iteraci&oacute;n, cuando la condici&oacute;n se comprueba, + se eval&uacute;a como &false; ($i no es m&aacute;s grande que 0) + y la ejecuci&oacute;n del bucle finaliza. + </simpara> + <para> + Los usuarios avanzados de C pueden estar familiarizados con un uso + distinto del bucle <literal>do..while</literal>, para permitir parar + la ejecuci&oacute;n en medio de los bloques de c&oacute;digo, encapsulandolos con + <literal>do..while</literal>(0), y usando la sentencia + <link linkend="control-structures.break"><literal>break</literal></link>. + El siguiente fragmento de c&oacute;digo demuestra esto: + <informalexample> + <programlisting role="php"> + do { + if ($i < 5) { + print "i no es lo suficientemente grande"; + break; + } + $i *= $factor; + if ($i < $minimum_limit) { + break; + } + print "i es correcto"; + ...procesa i... + } while(0); + </programlisting> + </informalexample> + </para> + <simpara> + No se preocupes si no entiende esto completamente o en absoluto. + Se pueden codificar archivos de comandos e incluso archivos de + comandos potentes sin usar esta 'propiedad'. + </simpara> + </sect1> + + <sect1 id="control-structures.for"> + <title><literal>for</literal></title> + <para> + Los bucles <literal>for</literal> son los bucles m&aacute;s complejos en + PHP. Se comportan como su contrapartida en C. La sintaxis de un + bucle <literal>for</literal> es: + <informalexample> + <programlisting> +for (expr1; expr2; expr3) sentencia + </programlisting> + </informalexample> + </para> + <simpara> + La primera expresi&oacute;n (<replaceable>expr1</replaceable>) se eval&uacute;a + (ejecuta) incondicionalmente una vez al principio del bucle. + </simpara> + <simpara> + Al comienzo de cada iteraci&oacute;n, se eval&uacute;a <replaceable>expr2 + </replaceable>. Si se eval&uacute;a como &true;, el + bucle contin&uacute;a y las sentencias anidadas se ejecutan. Si se eval&uacute;a + como &false;, la ejecuci&oacute;n del bucle finaliza. + </simpara> + <simpara> + Al final de cada iteraci&oacute;n, se eval&uacute;a (ejecuta) + <replaceable>expr3</replaceable>. + </simpara> + <simpara> + Cada una de las expresiones puede estar vac&iacute;a. + Que <replaceable>expr2</replaceable> est&eacute; vac&iacute;a significa + que el bucle deber&iacute;a correr indefinidamente (PHP implicitamente + lo considera como &true;, al igual que C). + Esto puede que no sea tan in&uacute;til como se podr&iacute;a pensar, puesto + que a menudo se quiere salir de un bucle usando una sentencia + <link linkend="control-structures.break"><literal>break</literal></link> + condicional en vez de usar la condici&oacute;n de <literal>for</literal>. + </simpara> + <para> + Considera los siguientes ejemplos. Todos ellos muestran n&uacute;meros del + 1 al 10: + + <informalexample> + <programlisting role="php"> + /* ejemplo 1 */ + + for ($i = 1; $i <= 10; $i++) { + print $i; + } + + /* ejemplo 2 */ + + for ($i = 1;;$i++) { + if ($i > 10) { + break; + } + print $i; + } + + /* ejemplo 3 */ + + $i = 1; + for (;;) { + if ($i > 10) { + break; + } + print $i; + $i++; + } + + /* ejemplo 4 */ + + for ($i = 1; $i <= 10; print $i, $i++) ; + </programlisting> + </informalexample> + </para> + <simpara> + Por supuesto, el primer ejemplo parece ser el mas elegante (o quiz&aacute;s + el cuarto), pero uno puede descubrir que ser capaz de usar expresiones + vac&iacute;as en bucles <literal>for</literal> resulta &uacute;til en muchas + ocasiones. + </simpara> + <para> + PHP tambi&eacute;n soporta la "sintaxis de dos puntos" alternativa para + bucles <literal>for</literal>. + <informalexample> + <programlisting> + for (expr1; expr2; expr3): sentencia; ...; endfor; + </programlisting> + </informalexample> + </para> + <para> + Otros lenguajes poseen una sentencia <literal>foreach</literal> para + traducir un array o una tabla hash. PHP3 no posee tal construcci&oacute;n; + PHP4 s&iacute; (ver <link linkend="control-structures.foreach">foreach</link>). + En PHP3, se puede combinar <link linkend="control-structures.while">while</link> + con las funciones <function>list</function> y <function>each</function> + para conseguir el mismo efecto. Mirar la documentaci&oacute;n de estas funciones + para ver un ejemplo. + </para> + </sect1> + + <sect1 id="control-structures.foreach"> + <title><literal>foreach</literal></title> + <para> + PHP4 (PHP3 no) incluye una construcci&oacute;n <literal>foreach</literal>, + tal como perl y algunos otros lenguajes. Esto simplemente da un + modo f&aacute;cil de iterar sobre arrays. Hay dos sintaxis; la segunda es + una extensi&oacute;n menor, pero &uacute;til de la primera: + <informalexample> + <programlisting> +foreach(expresion_array as $value) sentencia +foreach(expresion_array as $key => $value) sentencia + </programlisting> + </informalexample> + </para> + <simpara> + La primera forma recorre el array dado por + <literal>expresion_array</literal>. En cada iteraci&oacute;n, el valor del + elemento actual se asigna a <literal>$value</literal> y + el puntero interno del array se avanza en una unidad (as&iacute; en el siguiente + paso, se estar&aacute; mirando el elemento siguiente). + </simpara> + <simpara> + La segunda manera hace lo mismo, salvo que la clave del elemento + actual ser&aacute; asignada a la variable <literal>$key</literal> en cada + iteraci&oacute;n. + </simpara> + <para> + <note> + <para> + Cuando <literal>foreach</literal> comienza su primera ejecuci&oacute;n, + el puntero interno a la lista (array) se reinicia autom&aacute;ticamente al primer + elemento del array. Esto significa que no se necesita llamar a + <function>reset</function> antes de un bucle <literal>foreach</literal>. + </para> + </note> + </para> + <para> + <note> + <para> + Hay que tener en cuanta que<literal>foreach</literal> con una + copia de la lista (array) especificada y no la lista en si, por + ello el puntero de la lista no es modificado como en la construcci&oacute;n + each. + </para> + </note> + </para> + <para> + Puede haber observado que las siguientes son funcionalidades id&eacute;nticas: + <informalexample> + <programlisting role="php"> +reset( $arr ); +while( list( , $value ) = each( $arr ) ) { + echo "Valor: $value&lt;br&gt;\n"; +} + +foreach( $arr as $value ) { + echo "Valor: $value&lt;br&gt;\n"; +} + </programlisting> + </informalexample> + Las siguientes tambi&eacute;n son funcionalidades id&eacute;nticas: + <informalexample> + <programlisting role="php"> +reset( $arr ); +while( list( $key, $value ) = each( $arr ) ) { + echo "Key: $key; Valor: $value&lt;br&gt;\n"; +} + +foreach( $arr as $key => $value ) { + echo "Key: $key; Valor: $value&lt;br&gt;\n"; +} + </programlisting> + </informalexample> + </para> + <para> + Algunos ejemplos m&aacute;s para demostrar su uso: + <informalexample> + <programlisting role="php"> +/* foreach ejemplo 1: s&oacute;lo valor*/ +$a = array(1, 2, 3, 17); + +foreach($a as $v) { + print "Valor actual de \$a: $v.\n"; +} + +/* foreach ejemplo 2: valor (con clave impresa para ilustrar) */ +$a = array(1, 2, 3, 17); + +$i = 0; /* s&oacute;lo para prop&oacute;sitos demostrativos */ + +foreach($a as $v) { + print "\$a[$i] => $k.\n"; +} + +/* foreach ejemplo 3: clave y valor */ +$a = array( + "uno" => 1, + "dos" => 2, + "tres" => 3, + "diecisiete" => 17 +); + +foreach($a as $k => $v) { + print "\$a[$k] => $v.\n"; +} + </programlisting> + </informalexample> + </para> + </sect1> + + <sect1 id="control-structures.break"> + <title><literal>break</literal></title> + <simpara> + <literal>break</literal> escapa de la estructuras de control + iterante (bucle) actuales <literal>for</literal>, <literal>while</literal>, o + <literal>switch</literal>. + </simpara> + <simpara> + <literal>break</literal> accepta un par&aacute;metro opcional, el cual determina + cuantas estructuras de control hay que escapar. + </simpara> + <para> + <informalexample> + <programlisting role="php"> +$arr = array ('one', 'two', 'three', 'four', 'stop', 'five'); +while (list (, $val) = each ($arr)) { + if ($val == 'stop') { + break; /* You could also write 'break 1;' here. */ + } + echo "$val&lt;br&gt;\n"; +} + +/* Using the optional argument. */ + +$i = 0; +while (++$i) { + switch ($i) { + case 5: + echo "At 5&lt;br&gt;\n"; + break 1; /* Exit only the switch. */ + case 10: + echo "At 10; quitting&lt;br&gt;\n"; + break 2; /* Exit the switch and the while. */ + default: + break; + } +} + </programlisting> + </informalexample> + </para> + </sect1> + + <sect1 id="control-structures.continue"> + <title><literal>continue</literal></title> + + <simpara> + <literal>continue</literal> se usa dentro de la estructura del bucle + para saltar el resto de la iteraci&oacute;n actual del bucle y continuar + la ejecuci&oacute;n al comienzo de la siguiente iteraci&oacute;n. + </simpara> + <simpara> + <literal>continue</literal> accepta un par&aacute;metro opcional, el cual determina + cuantos niveles (bluces) hay que saltar antes de continuar con la ejecuci&oacute;n. + </simpara> + <para> + <informalexample> + <programlisting role="php"> + while (list($key,$value) = each($arr)) { + if ($key % 2) { // salta los miembros impares + continue; + } + do_something_odd ($value); + } +$i = 0; +while ($i++ &lt; 5) { + echo "Outer&lt;br&gt;\n"; + while (1) { + echo "&nbsp;&nbsp;Middle&lt;br&gt;\n"; + while (1) { + echo "&nbsp;&nbsp;Inner&lt;br&gt;\n"; + continue 3; + } + echo "This never gets output.&lt;br&gt;\n"; + } + echo "Neither does this.&lt;br&gt;\n"; +} + </programlisting> + </informalexample> + </para> + </sect1> + + <sect1 id="control-structures.switch"> + <title><literal>switch</literal></title> + + <simpara> + La sentencia <literal>switch</literal> es similar a una serie de + sentencias IF en la misma expresi&oacute;n. En muchas ocasiones, + se quiere comparar la misma variable (o expresi&oacute;n) con + nuchos valores diferentes, y ejecutar una parte de c&oacute;digo distinta + dependiendo de a qu&eacute; valor es igual. + Para ello sirve la sentencia <literal>switch</literal>. + </simpara> + <para> + Los siguientes dos ejemplos son dos modos distintos de escribir la + misma cosa, uno usa una serie de sentencias <literal>if</literal>, + y el otro usa la sentencia <literal>switch</literal>: + <informalexample> + <programlisting role="php"> + if ($i == 0) { + print "i es igual a 0"; + } + if ($i == 1) { + print "i es igual a 1"; + } + if ($i == 2) { + print "i es igual a 2"; + } + + switch ($i) { + case 0: + print "i es igual a 0"; + break; + case 1: + print "i es igual a 1"; + break; + case 2: + print "i es igual a 2"; + break; + } + </programlisting> + </informalexample> + </para> + <para> + Es importante entender c&oacute;mo se ejecuta la sentencia + <literal>switch</literal> para evitar errores. La + sentencia <literal>switch</literal> ejecuta l&iacute;nea por l&iacute;nea (realmente, + sentencia a sentencia). Al comienzo, no se ejecuta c&oacute;digo. + S&oacute;lo cuando se encuentra una sentencia <literal>case</literal> con un + valor que coincide con el valor de la expresi&oacute;n <literal>switch</literal> + PHP comienza a ejecutar las sentencias. PHP contin&uacute;a ejecutando las + sentencias hasta el final del bloque <literal>switch</literal>, + o la primera vez que vea una sentencia <literal>break</literal>. + Si no se escribe una sentencia <literal>break</literal> al final + de una lista de sentencias case, PHP seguir&aacute; ejecutando las sentencias + del siguiente case. Por ejemplo: + <informalexample> + <programlisting role="php"> + switch ($i) { + case 0: + print "i es igual a 0"; + case 1: + print "i es igual a 1"; + case 2: + print "i es igual a 2"; + } + </programlisting> + </informalexample> + </para> + <simpara> + Aqu&iacute;, si $i es igual a 0, ¡PHP ejecutar&iacute;a todas las sentecias print! + Si $i es igual a 1, PHP ejecutar&iacute;a las &uacute;ltimas dos sentencias print + y s&oacute;lo si $i es igual a 2, se obtendr&iacute;a la conducta 'esperada' + y solamente se mostrar&iacute;a 'i es igual a 2'. As&iacute;, es importante no + olvidar las sentencias <literal>break</literal> + (incluso aunque pueda querer evitar escribirlas intencionadamente + en ciertas circunstancias). + </simpara> + <simpara> + En una sentencia <literal>switch</literal>, la condici&oacute;n se + eval&uacute;a s&oacute;lo una vez y el resultado se compara a cada sentencia + <literal>case</literal>. En una sentencia <literal>elseif</literal>, + la condici&oacute;n se eval&uacute;a otra vez. Si tu condici&oacute;n es m&aacute;s complicada + que una comparaci&oacute;n simple y/o est&aacute; en un bucle estrecho, + un <literal>switch</literal> puede ser m&aacute;s r&aacute;pido. + </simpara> + <para> + La lista de sentencias de un case puede tambi&eacute;n estar vac&iacute;a, lo cual + simplemente pasa el control a la lista de sentencias del siguiente case. + <informalexample> + <programlisting role="php"> + switch ($i) { + case 0: + case 1: + case 2: + print "i es menor que 3, pero no negativo"; + break; + case 3: + print "i es 3"; + } + </programlisting> + </informalexample> + </para> + <para> + Un case especial es el default case. Este case coincide con + todo lo que no coincidan los otros case. Por ejemplo: + <informalexample> + <programlisting role="php"> + switch ($i) { + case 0: + print "i es igual a 0"; + break; + case 1: + print "i es igual a 1"; + break; + case 2: + print "i es igual a 2"; + break; + default: + print "i no es igual a 0, 1 o 2"; + } + </programlisting> + </informalexample> + </para> + <para> + La expresi&oacute;n <literal>case</literal> puede ser cualquier expresi&oacute;n + que se eval&uacute;e a un tipo simple, es decir, n&uacute;meros enteros o de punto + flotante y cadenas de texto. No se pueden usar aqu&iacute; ni arrays ni + objetos a menos que se conviertan a un tipo simple. + </para> + <para> + La sintaxis alternativa para las estructuras de control est&aacute; tambi&eacute;n + soportada con switch. Para m&aacute;s informaci&oacute;n, ver <link + linkend="control-structures.alternative-syntax">Sintaxis alternativa + para estructuras de control</link>. + <informalexample> + <programlisting role="php"> +switch ($i): + case 0: + print "i es igual 0"; + break; + case 1: + print "i es igual a 1"; + break; + case 2: + print "i es igual a 2"; + break; + default: + print "i no es igual a 0, 1 o 2"; + endswitch; + </programlisting> + </informalexample> + </para> + </sect1> + + <sect1 id="function.require"> + <title><function>require</function></title> + <simpara> + La sentencia <function>require</function> se sustituye a s&iacute; misma con + el archivo especificado, tal y como funciona la directiva + <literal>#include</literal> de C. + </simpara> + <simpara> + Un punto importante sobre su funcionamiento es que cuando un archivo se + incluye con <function>include</function> o se requiere con + <function>require</function>), el int&eacute;rprete sale del modo PHP + y entra en modo HTML al principio del archivo referenciado, + y vuelve de nuevo al modo PHP al final. Por esta raz&oacute;n, cualquier + c&oacute;digo dentro del archivo referenciado que debiera ser ejecutado + como c&oacute;digo PHP debe ser encerrado dentro de <link + linkend="language.basic-syntax.phpmode"> etiquetas v&aacute;lidas de + comienzo y fin de PHP</link>. + </simpara> + <simpara> + <function>require</function> no es en realidad una funci&oacute;n de PHP; + es m&aacute;s una construcci&oacute;n del lenguaje. Est&aacute; sujeta a algunas reglas + distintas de las de funciones. Por ejemplo, + <function>require</function> no esta sujeto a ninguna estructura de + control contenedora. Por otro lado, no devuelve ning&uacute;n valor; + intentar leer un valor de retorno de una llamada a un + <function>require</function> resulta en un error del int&eacute;rprete. + </simpara> + <simpara> + A diferencia de <function>include</function>, <function>require</function> + <emphasis>siempre</emphasis> leer&aacute; el archivo referenciado, + <emphasis>incluso si la l&iacute;nea en que est&aacute; no se ejecuta + nunca</emphasis>. Si se quiere incluir condicionalmente un archivo, se + usa <function>include</function>. La sentencia conditional no + afecta a <function>require</function>. No obstante, si la l&iacute;nea + en la cual aparece el <function>require</function> no se ejecuta, + tampoco se ejecutar&aacute; el c&oacute;digo del archivo referenciado. + </simpara> + <simpara> + De forma similar, las estructuras de bucle no afectan la conducta de + <function>require</function>. Aunque el c&oacute;digo contenido en el + archivo referenciado est&aacute; todav&iacute;a sujeto al bucle, el propio + <function>require</function> s&oacute;lo ocurre una vez. + </simpara> + <para> + Esto significa que no se puede poner una sentencia + <function>require</function> dentro de una estructura de bucle y + esperar que incluya el contenido de un archivo distinto en cada + iteraci&oacute;n. Para hacer esto, usa una sentencia + <function>include</function>. + <informalexample> + <programlisting role="php"> +require( 'header.inc' ); + </programlisting> + </informalexample> + </para> + <simpara> + When a file is <function>require</function>ed, the code it + contains inherits the variable scope of the line on which the + <function>require</function> occurs. Any variables available at + that line in the calling file will be available within the called + file. If the <function>require</function> occurs inside a + function within the calling file, then all of the code contained + in the called file will behave as though it had been defined + inside that function. + </simpara> + <para> + If the <function>require</function>ed file is called via HTTP + using the fopen wrappers, and if the target server interprets the + target file as PHP code, variables may be passed to the + <function>require</function>ed file using an URL request string as + used with HTTP GET. This is not strictly speaking the same thing + as <function>require</function>ing the file and having it inherit + the parent file's variable scope; the script is actually being run + on the remote server and the result is then being included into + the local script. + <informalexample> + <programlisting role="php"> +/* This example assumes that someserver is configured to parse .php + * files and not .txt files. Also, 'works' here means that the variables + * $varone and $vartwo are available within the require()ed file. */ + +/* Won't work; file.txt wasn't handled by someserver. */ +require ("http://someserver/file.txt?varone=1&amp;vartwo=2"); + +/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2' + * on the local filesystem. */ +require ("file.php?varone=1&amp;vartwo=2"); + +/* Works. */ +require ("http://someserver/file.php?varone=1&amp;vartwo=2"); + +$varone = 1; +$vartwo = 2; +require ("file.txt"); /* Works. */ +require ("file.php"); /* Works. */ + </programlisting> + </informalexample> + </para> + <simpara> + En PHP3, es posible ejecutar una sentencia <literal>return</literal> + dentro de un archivo referenciado con <function>require</function>, + en tanto en cuanto esa sentencia aparezca en el &aacute;mbito global del + archivo requerido (<function>require</function>). No puede aparecer + dentro de ning&uacute;n bloque (lo que siginifica dentro de llaves({})). + En PHP4, no obstante, esta capacidad ha sido desestimada. + Si se necesita esta funcionalidad, v&eacute;ase <function>include</function>. + </simpara> + <simpara> + Ver tambien <function>include</function>, <function>require_once</function>, + <function>include_once</function>, <function>readfile</function>, + y <function>virtual</function>. + </simpara> + </sect1> + + <sect1 id="function.include"> + <title><function>include</function></title> + <simpara> + La sentencia <function>include</function> incluye y eval&uacute;a + el archivo especificado. + </simpara> + <simpara> + Si "URL fopen wrappers" esta activada en PHP (como est&aacute; en la + configuraci&oacute;n inicial), se puede especificar el fichero que se + va a incluir usando una URL en vez de un fichero local (con su Path) + Ver <link linkend="features.remote-files">Ficheros remotos</link> + y <function>fopen</function> para m&aacute;s informaci&oacute;n. + </simpara> + <simpara> + Un punto importante sobre su funcionamiento es que cuando un archivo + se incluye con <function>include</function> o se requiere con + <function>require</function>, el int&eacute;rprete sale del modo PHP + y entra en modo HTML al principio del archivo referenciado, + y vuelve de nuevo al modo PHP al final. Por esta raz&oacute;n, cualquier + c&oacute;digo dentro del archivo referenciado que debiera ser ejecutado + como c&oacute;digo PHP debe ser encerrado dentro de <link + linkend="language.basic-syntax.phpmode"> etiquetas v&aacute;lidas de + comienzo y fin de PHP</link>. + </simpara> + <para> + Esto sucede cada vez que se encuentra la sentencia + <function>include</function>, as&iacute; que se puede usar una sentencia + <function>include</function> dentro de una estructura de bucle para + incluir un n&uacute;mero de archivos diferentes. + + <informalexample> + <programlisting role="php"> +$archivos = array ('primero.inc', 'segundo.inc', 'tercero.inc'); +for ($i = 0; $i < count($archivos); $i++) { + include $archivos[$i]; +} + </programlisting> + </informalexample> + </para> + <para> + <function>include</function> difiere de + <function>require</function> en que la sentencia include se + re-eval&uacute;a cada vez que se encuentra (y s&oacute;lo cuando est&aacute; siendo + ejecutada), mientras que la sentencia <function>require</function> + se reemplaza por el archivo referenciado cuando se encuentra por + primera vez, se vaya a evaluar el contenido del archivo o no + (por ejemplo, si est&aacute; dentro de una sentencia <link + linkend="control-structures.if">if</link> cuya condici&oacute;n evaluada + es falsa). + </para> + <para> + Debido a que <function>include</function> es una construcci&oacute;n especial + del lenguaje, se debe encerrar dentro de un bloque de sentencias si + est&aacute; dentro de un bloque condicional. + <informalexample> + <programlisting role="php"> + /* Esto es ERR&Oacute;NEO y no funcionar&aacute; como se desea. */ + + if ($condicion) + include($archivo); + else + include($otro); + + /* Esto es CORRECTO. */ + + if ($condicion) { + include($archivo); + } else { + include($otro); + } + </programlisting> + </informalexample> + </para> + <simpara> + En ambos, PHP3 y PHP4, es posible ejecutar una sentencia + <literal>return</literal> dentro de un archivo incluido con + <function>include</function>, para terminar el procesado de ese + archivo y volver al archivo de comandos que lo llam&oacute;. + Existen algunas diferencias en el modo en que esto funciona, + no obstante. La primera es que en PHP3, <literal>return</literal> + no puede aparecer dentro de un bloque a menos que sea un bloque de + funci&oacute;n, en el cual <literal>return</literal> se aplica a esa funci&oacute;n + y no al archivo completo. En PHP4, no obstante, esta restricci&oacute;n no + existe. Tambi&eacute;n, PHP4 permite devolver valores desde archivos + incluidos con <function>include</function>. Se puede capturar el valor de la + llamada a <function>include</function> como se har&iacute;a con una + funci&oacute;n normal. Esto genera un error de int&eacute;rprete en PHP3. + </simpara> + <example> + <title><function>include</function> en PHP3 y PHP4</title> + <para> + Asumamos la existencia del siguiente archivo (llamado + <filename>test.inc</filename>) en el mismo directorio que el + archivo principal: + <programlisting role="php"> +&lt?php +echo "Antes del return &lt;br&gt;\n"; +if ( 1 ) { + return 27; +} +echo "Despu&eacute;s del return &lt;br&gt;\n"; +?&gt; + </programlisting> + </para> + <para> + Asumamos que el archivo principal (<filename>main.html</filename>) + contiene lo siguiente: + <programlisting role="php"> +&lt?php +$retval = include( 'test.inc' ); +echo "El archivo devolvi&oacute;: '$retval'&lt;br&gt;\n"; +?&gt; + </programlisting> + </para> + <para> + Cuando se llama a <filename>main.html</filename> en PHP3, + generar&aacute; un error del int&eacute;rprete en la linea 2; no se puede + capturar el valor de un <function>include</function> en PHP3. + En PHP4, no obstante, el resultado ser&aacute;: + <screen> +Antes del return +El archivo devolvi&oacute;: '27' + </screen> + </para> + <para> + Ahora, asumamos que se ha modificado <filename>main.html</filename> + para que contenga lo siguiente: + <programlisting role="php"> +&lt?php +include( 'test.inc' ); +echo "De vuelta en main.html&lt;br&gt;\n"; +?&gt; + </programlisting> + </para> + <para> + En PHP4, la salida ser&aacute;: + <screen> +Antes del return +De vuelta en main.html + </screen> + No obstante, PHP3 dar&aacute; la siguiente salida: + <screen> +Antes del return +27De vuelta en main.html + +Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5 + </screen> + </para> + <para> + El error del int&eacute;rprete es resultado del hecho de que la sentencia + <literal>return</literal> est&aacute; encerrada en un bloque de no-funci&oacute;n + dentro de <filename>test.inc</filename>. Cuando el return se mueve + fuera del bloque, la salida es: + <screen> +Antes del return +27De vuelta en main.html + </screen> + </para> + <para> + El '27' esp&uacute;reo se debe al hecho de que PHP3 no soporta devolver + valores con <literal>return</literal> desde archivos como ese. + </para> + </example> + <simpara> + When a file is <function>include</function>ed, the code it + contains inherits the variable scope of the line on which the + <function>include</function> occurs. Any variables available at + that line in the calling file will be available within the called + file. If the <function>include</function> occurs inside a + function within the calling file, then all of the code contained + in the called file will behave as though it had been defined + inside that function. + </simpara> + <para> + If the <function>include</function>ed file is called via HTTP + using the fopen wrappers, and if the target server interprets the + target file as PHP code, variables may be passed to the + <function>include</function>ed file using an URL request string as + used with HTTP GET. This is not strictly speaking the same thing + as <function>include</function>ing the file and having it inherit + the parent file's variable scope; the script is actually being run + on the remote server and the result is then being included into + the local script. + <informalexample> + <programlisting role="php"> +/* This example assumes that someserver is configured to parse .php + * files and not .txt files. Also, 'works' here means that the variables + * $varone and $vartwo are available within the include()ed file. */ + +/* Won't work; file.txt wasn't handled by someserver. */ +include ("http://someserver/file.txt?varone=1&amp;vartwo=2"); + +/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2' + * on the local filesystem. */ +include ("file.php?varone=1&amp;vartwo=2"); + +/* Works. */ +include ("http://someserver/file.php?varone=1&amp;vartwo=2"); + +$varone = 1; +$vartwo = 2; +include ("file.txt"); /* Works. */ +include ("file.php"); /* Works. */ + </programlisting> + </informalexample> + </para> + <simpara> + See also <function>require</function>, <function>require_once</function>, + <function>include_once</function>, <function>readfile</function>, + and <function>virtual</function>. + </simpara> + </sect1> + + <sect1 id="function.require-once"> + <title><function>require_once</function></title> + <para> + The <function>require_once</function> statement replaces + itself with the specified file, much like the C preprocessor's + <literal>#include</literal> works, and in that respect is + similar to the <function>require</function> statement. The main + difference is that in an inclusion chain, the use of + <function>require_once</function> will assure that the code is + added to your script only once, and avoid clashes with variable + values or function names that can happen. + </para> + <para> + For example, if you create the following 2 include files + <literal>utils.inc</literal> and <literal>foolib.inc</literal> + <example> + <title>utils.inc</title> + <programlisting role="php"> +&lt;?php +define(PHPVERSION, floor(phpversion())); +echo "GLOBALS ARE NICE\n"; +function goodTea() { + return "Oolong tea tastes good!"; +} +?&gt; + </programlisting> + </example> + <example> + <title>foolib.inc</title> + <programlisting role="php"> +&lt;?php +require ("utils.inc"); +function showVar($var) { + if (PHPVERSION == 4) { + print_r($var); + } else { + dump_var($var); + } +} + +// bunch of other functions ... +?&gt; + </programlisting> + </example> + And then you write a script <literal>cause_error_require.php</literal> + <example> + <title>cause_error_require.php</title> + <programlisting role="php"> +&lt;?php +require("foolib.inc"); +/* the following will generate an error */ +require("utils.inc"); +$foo = array("1",array("complex","quaternion")); +echo "this is requiring utils.inc again which is also\n"; +echo "required in foolib.inc\n"; +echo "Running goodTea: ".goodTea()."\n"; +echo "Printing foo: \n"; +showVar($foo); +?&gt; + </programlisting> + </example> + When you try running the latter one, the resulting ouptut will be (using + PHP 4.01pl2): + <informalexample> + <programlisting> +GLOBALS ARE NICE +GLOBALS ARE NICE + +Fatal error: Cannot redeclare causeerror() in utils.inc on line 5 + </programlisting> + </informalexample> + By modifying <literal>foolib.inc</literal> and + <literal>cause_errror_require.php</literal> + to use <function>require_once</function> + instead of <function>require</function> and renaming the + last one to <literal>avoid_error_require_once.php</literal>, we have: + <example> + <title>foolib.inc (fixed)</title> + <programlisting role="php"> +... +require_once("utils.inc"); +function showVar($var) { +... + </programlisting> + </example> + <example> + <title>avoid_error_require_once.php</title> + <programlisting role="php"> +... +require_once("foolib.inc"); +require_once("utils.inc"); +$foo = array("1",array("complex","quaternion")); +... + </programlisting> + </example> + And when running the latter, the output will be (using PHP 4.0.1pl2): + <informalexample> + <programlisting> +GLOBALS ARE NICE +this is requiring globals.inc again which is also +required in foolib.inc +Running goodTea: Oolong tea tastes good! +Printing foo: +Array +( + [0] =&gt; 1 + [1] =&gt; Array + ( + [0] =&gt; complex + [1] =&gt; quaternion + ) + +) + </programlisting> + </informalexample> + </para> + <para> + Also note that, analogous to the behavior of the + <literal>#include</literal> of the C preprocessor, this statement + acts at "compile time", e.g. when the script is parsed and before it + is executed, and should not be used for parts of the script that need + to be inserted dynamically during its execution. You should use + <function>include_once</function> or <function>include</function> + for that purpose. + </para> + <para> + For more examples on using <function>require_once</function> and + <function>include_once</function>, look at the PEAR code included in + the latest PHP source code distributions. + </para> + <para> + See also: <function>require</function>, + <function>include</function>, <function>include_once</function>, + <function>get_required_files</function>, + <function>get_included_files</function>, <function>readfile</function>, + and <function>virtual</function>. + </para> + </sect1> + + <sect1 id="function.include-once"> + <title><function>include_once</function></title> + <para> + The <function>include_once</function> statement includes and evaluates + the specified file during the execution of the script. + This is a behavior similar to the <function>include</function> statement, + with the important difference that if the code from a file has already + been included, it will not be included again. + </para> + <para> + As mentioned in the <function>require_once</function> description, the + <function>include_once</function> should be used in the cases in which + the same file might be included and evaluated more than once during a + particular execution of a script, and you want to be sure that it is + included exactly once to avoid problems with function redefinitions, + variable value reassignments, etc. + </para> + <para> + For more examples on using <function>require_once</function> and + <function>include_once</function>, look at the PEAR code included in + the latest PHP source code distributions. + </para> + <para> + See also: <function>require</function>, + <function>include</function>, <function>require_once</function>, + <function>get_required_files</function>, + <function>get_included_files</function>, <function>readfile</function>, + and <function>virtual</function>. + </para> + </sect1> + + </chapter> + + <!-- Keep this comment at the end of the file + Local variables: + mode: sgml + sgml-omittag:t + sgml-shorttag:t + sgml-minimize-attributes:nil + sgml-always-quote-attributes:t + sgml-indent-step:1 + sgml-indent-data:t + sgml-parent-document:nil + sgml-default-dtd-file:"../../manual.ced" + sgml-exposed-tags:nil + sgml-local-catalogs:nil + sgml-local-ecat-files:nil + End: + --> Index: phpdoc/es/language/expressions.xml diff -u phpdoc/es/language/expressions.xml:1.3 phpdoc/es/language/expressions.xml:1.4 --- phpdoc/es/language/expressions.xml:1.3 Sat Jul 7 18:20:19 2001 +++ phpdoc/es/language/expressions.xml Sat Jul 7 19:11:27 2001 @@ -1,195 +1,195 @@ - <chapter id="language.expressions"> - <title>Expresiones</title> - - <simpara> - Las expresiones son la piedra angular de PHP. En PHP, casi cualquier - cosa que escribes es una expresi&oacute;n. La forma m&aacute;s simple y ajustada de - definir una expresi&oacute;n es "cualquier cosa que tiene un valor".</simpara> - - <simpara> - Las formas m&aacute;s b&aacute;sicas de expresiones son las constantes y las variables. - Cuando escribes "$a = 5", est&aacute;s asignando '5' a $a. '5', obviamente, - tiene el valor 5 o, en otras palabras '5' es una expresi&oacute;n con el valor 5 - (en este caso, '5' es una constante entera).</simpara> - - <simpara> - Despu&eacute;s de esta asignaci&oacute;n, esperar&aacute;s que el valor de $a sea 5 - tambi&eacute;n, de manera que si escribes $b = $a, esperas que se comporte - igual que si escribieses $b = 5. En otras palabras, $a es una expresi&oacute;n - tambi&eacute;n con el valor 5. Si todo va bien, eso es exactamente lo que pasar&aacute;. - </simpara> - - <para> - Las funciones son un ejemplo algo m&aacute;s complejo de expresiones. Por ejemplo, - considera la siguiente funci&oacute;n: - - <informalexample> - <programlisting> -function foo () { - return 5; -} - </programlisting> - </informalexample></para> - - <simpara> - Suponiendo que est&eacute;s familiarizado con el concepto de funciones (si no lo est&aacute;s - &eacute;chale un vistazo al cap&iacute;tulo sobre funciones), asumir&aacute;s que teclear - <literal>$c = foo()</literal> es esencialmente lo mismo que escribir - <literal>$c = 5</literal>, y has acertado. Las funciones son expresiones - que valen el valor que retornan. Como foo() devuelve 5, el valor de la expresi&oacute;n 'foo()' - es 5. Normalmente las funciones no devuelven un valor fijo, sino que - suele ser calculado.</simpara> - - <simpara> - Desde luego, los valores en PHP no se limitan a enteros, y lo m&aacute;s normal es - que no lo sean. PHP soporta tres tipos escalares: enteros, punto flotante y - cadenas (los tipos escalares son aquellos cuyos valores no pueden 'dividirse' - en partes menores, no como los arrays, por ejemplo). - PHP tambi&eacute;n soporta dos tipos compuestos (no escalares): arrays y objetos. - Se puede asignar cada uno de estos tipos de valor a variables o bien retornarse - de funciones, sin ning&uacute;n tipo de limitaci&oacute;n.</simpara> - - <simpara> - Hasta aqu&iacute;, los usuarios de PHP/FI 2 no deber&iacute;an haber notado ning&uacute;n cambio. - Sin embargo, PHP lleva las expresiones mucho m&aacute;s all&aacute;, al igual que otros lenguajes. - PHP es un lenguaje orientado a expresiones, en el sentido de que casi todo es una - expresi&oacute;n. Considera el ejemplo anterior '$a = 5'. Es sencillo ver que - hay dos valores involucrados, el valor de la constante entera '5', y el valor de $a - que est&aacute; siendo actualizado tambi&eacute;n a 5. Pero la verdad es que hay un valor - adicional implicado aqu&iacute;, y es el valor de la propia asignaci&oacute;n. - La asignaci&oacute;n misma se eval&uacute;a al valor asignado, en este caso 5. - En la pr&aacute;ctica, quiere decir que '$a = 5', independientemente de lo que hace, - es una expresi&oacute;n con el valor 5. De esta manera, escribir algo como - '$b = ($a = 5)' es como escribir '$a = 5; $b = 5;' (un punto y coma - marca el final de una instrucci&oacute;n). Como las asignaciones se eval&uacute;an - de derecha a izquierda, puedes escribir tambi&eacute;n '$b = $a = 5'.</simpara> - - <simpara> - Otro buen ejemplo de orientaci&oacute;n a expresiones es el pre y post incremento - y decremento. Los usuarios de PHP/FI 2 y los de otros muchos - lenguajes les sonar&aacute; la notaci&oacute;n variable++ y variable--. Esto son las - operaciones de incremento y decremento. En PHP/FI 2, la instrucci&oacute;n '$a++' - no tiene valor (no es una expresi&oacute;n), y no puedes asignarla o usarla - de ning&uacute;n otro modo. - PHP mejora las caracter&iacute;sticas del incremento/decremento haci&eacute;ndolos tambi&eacute;n - expresiones, como en C. En PHP, como en C, hay dos tipos de incremento - - pre-incremento y post-incremento. Ambos, en esencia, incrementan la variable - y el efecto en la variable es id&eacute;ntico. La diferencia radica en el valor - de la propia expresion incremento. - El preincremento , escrito '++$variable', se eval&uacute;a al valor incrementado - (PHP incrementa la variable antes de leer su valor, de ah&iacute; el nombre 'preincremento'). - El postincremento, escrito '$variable++', se eval&uacute;a al valor original de - $variable antes de realizar el incremento (PHP incrementa la variable - despu&eacute;s de leer su valor, de ah&iacute; el nombre 'postincremento').</simpara> - - <simpara> - Un tipo muy corriente de expresiones son las expresiones de comparaci&oacute;n. - Estas expresiones se eval&uacute;an a 0 o 1, significando FALSO (&false;) o - CIERTO (&true;), respectivamente. PHP soporta > (mayor que), >= (mayor - o igual que), == (igual que), != (distinto), < (menor que) y <= - (menor o igual que). Estas expresiones se usan frecuentemente dentro - de la ejecuci&oacute;n condicional como la instrucci&oacute;n <literal>if</literal>.</simpara> - - <simpara> - El &uacute;ltimo tipo de expresiones que trataremos, es la combinaci&oacute;n operador-asignaci&oacute;n. - Ya sabes que si quieres incrementar $a en 1, basta con escribir '$a++' o ++$a'. - Pero qu&eacute; pasa si quieres a&ntilde;adir m&aacute;s de 1, por ejemplo 3? - Podr&iacute;as escribir '$a++' m&uacute;ltiples veces, pero no es una forma de hacerlo - ni eficiente ni c&oacute;moda. Una pr&aacute;ctica mucho m&aacute;s corriente es escribir - '$a = $a + 3'. '$a + 3' se eval&uacute;a al valor de $a m&aacute;s 3, y se asigna de nuevo - a $a, lo que resulta en incrementar $a en 3. En PHP, como en otros lenguajes - como C, puedes escribir esto de una forma m&aacute;s concisa, que con el tiempo - ser&aacute; m&aacute;s clara y tambi&eacute;n f&aacute;cil de entender. A&ntilde;adir 3 al valor actual - de $a se puede escribir como '$a += 3'. Esto quiere decir exactamente - "toma el valor de $a, s&uacute;male 3, y as&iacute;gnalo otra vez a $a". - Adem&aacute;s de ser m&aacute;s corto y claro, tambi&eacute;n resulta en una ejecuci&oacute;n m&aacute;s r&aacute;pida. - El valor de '$a += 3', como el valor de una asignaci&oacute;n normal y corriente, es - el valor asignado. Ten en cuenta que NO es 3, sino el valor combinado de $a m&aacute;s 3 - (&eacute;se es el valor asignado a $a). Cualquier operaci&oacute;n binaria puede ser usada - en forma de operador-asignaci&oacute;n, por ejemplo '$a -= 5' (restar 5 del valor de $a), - '$b *= 7' (multiplicar el valor de $b por 5), etc.</simpara> - - <para> - Hay otra expresi&oacute;n que puede parecer extra&ntilde;a si no la has visto en otros lenguaes, - el operador condicional ternario: - - <informalexample><programlisting> -$first ? $second : $third -</programlisting></informalexample> - - Si el valor de la primera subexpresi&oacute;n es verdadero (distinto de cero), - entonces se eval&uacute;a la segunda subexpresi&oacute;n, si no, se eval&uacute;a la tercera y - &eacute;se es el valor.</para> - - <para> - El siguiente ejemplo te ayudar&aacute; a comprender un poco mejor el pre y post incremento - y las expresiones en general: - - <informalexample> - <programlisting> -function double($i) { - return $i*2; -} -$b = $a = 5; /* asignar el valor cinco a las variables $a y $b */ -$c = $a++; /* postincremento, asignar el valor original de $a (5) a $c */ -$e = $d = ++$b; /* preincremento, asignar el valor incrementado de $b (6) a - $d y a $e */ - -/* en este punto, tanto $d como $e son iguales a 6 */ - -$f = double($d++); /* asignar el doble del valor de $d <emphasis>antes</emphasis> - del incremento, 2*6 = 12 a $f */ -$g = double(++$e); /* asignar el doble del valor de $e <emphasis>despu&eacute;s</emphasis> - del incremento, 2*7 = 14 a $g */ -$h = $g += 10; /* primero, $g es incrementado en 10 y termina valiendo 24. - despu&eacute;s el valor de la asignaci&oacute;n (24) se asigna a $h, - y $h tambi&eacute;n acaba valiendo 24. */ -</programlisting></informalexample></para> - - <simpara> - Al principio del cap&iacute;tulo hemos dicho que describir&iacute;amos los distintos - tipos de instrucciones y, como prometimos, las expresiones pueden ser - instrucciones. Sin embargo, no todas las expresiones son instrucciones. - En este caso, una instrucci&oacute;n tiene la forma 'expr' ';', es decir, - una expresi&oacute;n seguida de un punto y coma. En '$b=$a=5;', $a=5 es una - expresi&oacute;n v&aacute;lida, pero no es una instrucci&oacute;n en s&iacute; misma. Por otro lado - '$b=$a=5:' s&iacute; es una instrucci&oacute;n v&aacute;lida.</simpara> - - <simpara> - Una &uacute;ltima cosa que vale la pena mencionar, es el valor booleano de las - expresiones. En muchas ocasiones, principalmente en condicionales y bucles, - no est&aacute;s interesado en el valor exacto de la expresi&oacute;n, sino &uacute;nicamente si - es CIERTA (&true;) o FALSA (&false;) (PHP no tiene un tipo booleano espec&iacute;fico). - El valor de verdad de las expresiones en PHP se calcula de forma similar a perl. - Cualquier valor num&eacute;rico distinto de cero es CIERTO (&true;), cero es FALSO (&false;). - F&iacute;jate en que los valores negativos son distinto de cero y considerados CIERTO (&true;)! - La cadena vac&iacute;a y la cadena "0" son FALSO (&false;); todas las dem&aacute;s cadenas son &true;. - Con los tipos no escalares (arrays y objetos) - si el valor no contiene elementos - se considera FALSO (&false;), en caso contrario se considera CIERTO (&true;).</simpara> - - <simpara> - PHP te brinda una completa y potente implementaci&oacute;n de expresiones, y - documentarla enteramente est&aacute; m&aacute;s all&aacute; del objetivo de ete manual. - Los ejemplos anteriores, deber&iacute;an darte una buena idea de qu&eacute; son las - expresiones y c&oacute;mo construir expresiones &uacute;tiles. A lo largo del resto - del manual, escribiremos <replaceable>expr</replaceable> para indicar - una expresi&oacute;n PHP v&aacute;lida.</simpara> - - </chapter> - - <!-- Keep this comment at the end of the file - Local variables: - mode: sgml - sgml-omittag:t - sgml-shorttag:t - sgml-minimize-attributes:nil - sgml-always-quote-attributes:t - sgml-indent-step:1 - sgml-indent-data:t - sgml-parent-document:nil - sgml-default-dtd-file:"../manual.ced" - sgml-exposed-tags:nil - sgml-local-catalogs:nil - sgml-local-ecat-files:nil - End: - --> + <chapter id="language.expressions"> + <title>Expresiones</title> + + <simpara> + Las expresiones son la piedra angular de PHP. En PHP, casi cualquier + cosa que escribes es una expresi&oacute;n. La forma m&aacute;s simple y ajustada de + definir una expresi&oacute;n es "cualquier cosa que tiene un valor".</simpara> + + <simpara> + Las formas m&aacute;s b&aacute;sicas de expresiones son las constantes y las variables. + Cuando escribes "$a = 5", est&aacute;s asignando '5' a $a. '5', obviamente, + tiene el valor 5 o, en otras palabras '5' es una expresi&oacute;n con el valor 5 + (en este caso, '5' es una constante entera).</simpara> + + <simpara> + Despu&eacute;s de esta asignaci&oacute;n, esperar&aacute;s que el valor de $a sea 5 + tambi&eacute;n, de manera que si escribes $b = $a, esperas que se comporte + igual que si escribieses $b = 5. En otras palabras, $a es una expresi&oacute;n + tambi&eacute;n con el valor 5. Si todo va bien, eso es exactamente lo que pasar&aacute;. + </simpara> + + <para> + Las funciones son un ejemplo algo m&aacute;s complejo de expresiones. Por ejemplo, + considera la siguiente funci&oacute;n: + + <informalexample> + <programlisting> +function foo () { + return 5; +} + </programlisting> + </informalexample></para> + + <simpara> + Suponiendo que est&eacute;s familiarizado con el concepto de funciones (si no lo est&aacute;s + &eacute;chale un vistazo al cap&iacute;tulo sobre funciones), asumir&aacute;s que teclear + <literal>$c = foo()</literal> es esencialmente lo mismo que escribir + <literal>$c = 5</literal>, y has acertado. Las funciones son expresiones + que valen el valor que retornan. Como foo() devuelve 5, el valor de la expresi&oacute;n 'foo()' + es 5. Normalmente las funciones no devuelven un valor fijo, sino que + suele ser calculado.</simpara> + + <simpara> + Desde luego, los valores en PHP no se limitan a enteros, y lo m&aacute;s normal es + que no lo sean. PHP soporta tres tipos escalares: enteros, punto flotante y + cadenas (los tipos escalares son aquellos cuyos valores no pueden 'dividirse' + en partes menores, no como los arrays, por ejemplo). + PHP tambi&eacute;n soporta dos tipos compuestos (no escalares): arrays y objetos. + Se puede asignar cada uno de estos tipos de valor a variables o bien retornarse + de funciones, sin ning&uacute;n tipo de limitaci&oacute;n.</simpara> + + <simpara> + Hasta aqu&iacute;, los usuarios de PHP/FI 2 no deber&iacute;an haber notado ning&uacute;n cambio. + Sin embargo, PHP lleva las expresiones mucho m&aacute;s all&aacute;, al igual que otros lenguajes. + PHP es un lenguaje orientado a expresiones, en el sentido de que casi todo es una + expresi&oacute;n. Considera el ejemplo anterior '$a = 5'. Es sencillo ver que + hay dos valores involucrados, el valor de la constante entera '5', y el valor de $a + que est&aacute; siendo actualizado tambi&eacute;n a 5. Pero la verdad es que hay un valor + adicional implicado aqu&iacute;, y es el valor de la propia asignaci&oacute;n. + La asignaci&oacute;n misma se eval&uacute;a al valor asignado, en este caso 5. + En la pr&aacute;ctica, quiere decir que '$a = 5', independientemente de lo que hace, + es una expresi&oacute;n con el valor 5. De esta manera, escribir algo como + '$b = ($a = 5)' es como escribir '$a = 5; $b = 5;' (un punto y coma + marca el final de una instrucci&oacute;n). Como las asignaciones se eval&uacute;an + de derecha a izquierda, puedes escribir tambi&eacute;n '$b = $a = 5'.</simpara> + + <simpara> + Otro buen ejemplo de orientaci&oacute;n a expresiones es el pre y post incremento + y decremento. Los usuarios de PHP/FI 2 y los de otros muchos + lenguajes les sonar&aacute; la notaci&oacute;n variable++ y variable--. Esto son las + operaciones de incremento y decremento. En PHP/FI 2, la instrucci&oacute;n '$a++' + no tiene valor (no es una expresi&oacute;n), y no puedes asignarla o usarla + de ning&uacute;n otro modo. + PHP mejora las caracter&iacute;sticas del incremento/decremento haci&eacute;ndolos tambi&eacute;n + expresiones, como en C. En PHP, como en C, hay dos tipos de incremento - + pre-incremento y post-incremento. Ambos, en esencia, incrementan la variable + y el efecto en la variable es id&eacute;ntico. La diferencia radica en el valor + de la propia expresion incremento. + El preincremento , escrito '++$variable', se eval&uacute;a al valor incrementado + (PHP incrementa la variable antes de leer su valor, de ah&iacute; el nombre 'preincremento'). + El postincremento, escrito '$variable++', se eval&uacute;a al valor original de + $variable antes de realizar el incremento (PHP incrementa la variable + despu&eacute;s de leer su valor, de ah&iacute; el nombre 'postincremento').</simpara> + + <simpara> + Un tipo muy corriente de expresiones son las expresiones de comparaci&oacute;n. + Estas expresiones se eval&uacute;an a 0 o 1, significando FALSO (&false;) o + CIERTO (&true;), respectivamente. PHP soporta > (mayor que), >= (mayor + o igual que), == (igual que), != (distinto), < (menor que) y <= + (menor o igual que). Estas expresiones se usan frecuentemente dentro + de la ejecuci&oacute;n condicional como la instrucci&oacute;n <literal>if</literal>.</simpara> + + <simpara> + El &uacute;ltimo tipo de expresiones que trataremos, es la combinaci&oacute;n operador-asignaci&oacute;n. + Ya sabes que si quieres incrementar $a en 1, basta con escribir '$a++' o ++$a'. + Pero qu&eacute; pasa si quieres a&ntilde;adir m&aacute;s de 1, por ejemplo 3? + Podr&iacute;as escribir '$a++' m&uacute;ltiples veces, pero no es una forma de hacerlo + ni eficiente ni c&oacute;moda. Una pr&aacute;ctica mucho m&aacute;s corriente es escribir + '$a = $a + 3'. '$a + 3' se eval&uacute;a al valor de $a m&aacute;s 3, y se asigna de nuevo + a $a, lo que resulta en incrementar $a en 3. En PHP, como en otros lenguajes + como C, puedes escribir esto de una forma m&aacute;s concisa, que con el tiempo + ser&aacute; m&aacute;s clara y tambi&eacute;n f&aacute;cil de entender. A&ntilde;adir 3 al valor actual + de $a se puede escribir como '$a += 3'. Esto quiere decir exactamente + "toma el valor de $a, s&uacute;male 3, y as&iacute;gnalo otra vez a $a". + Adem&aacute;s de ser m&aacute;s corto y claro, tambi&eacute;n resulta en una ejecuci&oacute;n m&aacute;s r&aacute;pida. + El valor de '$a += 3', como el valor de una asignaci&oacute;n normal y corriente, es + el valor asignado. Ten en cuenta que NO es 3, sino el valor combinado de $a m&aacute;s 3 + (&eacute;se es el valor asignado a $a). Cualquier operaci&oacute;n binaria puede ser usada + en forma de operador-asignaci&oacute;n, por ejemplo '$a -= 5' (restar 5 del valor de $a), + '$b *= 7' (multiplicar el valor de $b por 5), etc.</simpara> + + <para> + Hay otra expresi&oacute;n que puede parecer extra&ntilde;a si no la has visto en otros lenguaes, + el operador condicional ternario: + + <informalexample><programlisting> +$first ? $second : $third +</programlisting></informalexample> + + Si el valor de la primera subexpresi&oacute;n es verdadero (distinto de cero), + entonces se eval&uacute;a la segunda subexpresi&oacute;n, si no, se eval&uacute;a la tercera y + &eacute;se es el valor.</para> + + <para> + El siguiente ejemplo te ayudar&aacute; a comprender un poco mejor el pre y post incremento + y las expresiones en general: + + <informalexample> + <programlisting> +function double($i) { + return $i*2; +} +$b = $a = 5; /* asignar el valor cinco a las variables $a y $b */ +$c = $a++; /* postincremento, asignar el valor original de $a (5) a $c */ +$e = $d = ++$b; /* preincremento, asignar el valor incrementado de $b (6) a + $d y a $e */ + +/* en este punto, tanto $d como $e son iguales a 6 */ + +$f = double($d++); /* asignar el doble del valor de $d <emphasis>antes</emphasis> + del incremento, 2*6 = 12 a $f */ +$g = double(++$e); /* asignar el doble del valor de $e <emphasis>despu&eacute;s</emphasis> + del incremento, 2*7 = 14 a $g */ +$h = $g += 10; /* primero, $g es incrementado en 10 y termina valiendo 24. + despu&eacute;s el valor de la asignaci&oacute;n (24) se asigna a $h, + y $h tambi&eacute;n acaba valiendo 24. */ +</programlisting></informalexample></para> + + <simpara> + Al principio del cap&iacute;tulo hemos dicho que describir&iacute;amos los distintos + tipos de instrucciones y, como prometimos, las expresiones pueden ser + instrucciones. Sin embargo, no todas las expresiones son instrucciones. + En este caso, una instrucci&oacute;n tiene la forma 'expr' ';', es decir, + una expresi&oacute;n seguida de un punto y coma. En '$b=$a=5;', $a=5 es una + expresi&oacute;n v&aacute;lida, pero no es una instrucci&oacute;n en s&iacute; misma. Por otro lado + '$b=$a=5:' s&iacute; es una instrucci&oacute;n v&aacute;lida.</simpara> + + <simpara> + Una &uacute;ltima cosa que vale la pena mencionar, es el valor booleano de las + expresiones. En muchas ocasiones, principalmente en condicionales y bucles, + no est&aacute;s interesado en el valor exacto de la expresi&oacute;n, sino &uacute;nicamente si + es CIERTA (&true;) o FALSA (&false;) (PHP no tiene un tipo booleano espec&iacute;fico). + El valor de verdad de las expresiones en PHP se calcula de forma similar a perl. + Cualquier valor num&eacute;rico distinto de cero es CIERTO (&true;), cero es FALSO (&false;). + F&iacute;jate en que los valores negativos son distinto de cero y considerados CIERTO (&true;)! + La cadena vac&iacute;a y la cadena "0" son FALSO (&false;); todas las dem&aacute;s cadenas son &true;. + Con los tipos no escalares (arrays y objetos) - si el valor no contiene elementos + se considera FALSO (&false;), en caso contrario se considera CIERTO (&true;).</simpara> + + <simpara> + PHP te brinda una completa y potente implementaci&oacute;n de expresiones, y + documentarla enteramente est&aacute; m&aacute;s all&aacute; del objetivo de ete manual. + Los ejemplos anteriores, deber&iacute;an darte una buena idea de qu&eacute; son las + expresiones y c&oacute;mo construir expresiones &uacute;tiles. A lo largo del resto + del manual, escribiremos <replaceable>expr</replaceable> para indicar + una expresi&oacute;n PHP v&aacute;lida.</simpara> + + </chapter> + + <!-- Keep this comment at the end of the file + Local variables: + mode: sgml + sgml-omittag:t + sgml-shorttag:t + sgml-minimize-attributes:nil + sgml-always-quote-attributes:t + sgml-indent-step:1 + sgml-indent-data:t + sgml-parent-document:nil + sgml-default-dtd-file:"../manual.ced" + sgml-exposed-tags:nil + sgml-local-catalogs:nil + sgml-local-ecat-files:nil + End: + --> Index: phpdoc/es/language/functions.xml diff -u phpdoc/es/language/functions.xml:1.2 phpdoc/es/language/functions.xml:1.3 --- phpdoc/es/language/functions.xml:1.2 Thu Aug 24 02:51:15 2000 +++ phpdoc/es/language/functions.xml Sat Jul 7 19:11:27 2001 @@ -1,342 +1,342 @@ - <chapter id="functions"> - <title>Funciones</title> - - <sect1 id="functions.user-defined"> - <title>Funciones definidas por el usuario</title> - - <para> - Una funci&oacute;n se define con la siguiente sintaxis: - - <informalexample> - <programlisting role="php"> -function foo ($arg_1, $arg_2, ..., $arg_n) { - echo "Funci&oacute;n de ejemplo.\n"; - return $retval; -} - </programlisting> - </informalexample> - </para> - - <simpara> - Cualquier instrucci&oacute;n v&aacute;lida de PHP puede aparecer en el cuerpo - de la funci&oacute;n, incluso otras funiones y definiciones de - <link linkend="keyword.class">clases</link>. - </simpara> - <simpara> - En PHP3, las funciones deben definirse antes de que se referencien. - En PHP4 no existe tal requerimiento. - </simpara> - <simpara> - PHP no soporta la sobrecarga de funciones, y tampoco es posible - redefinir u ocultar funciones previamente declaradas. - </simpara> - <simpara> - PHP3 no soporta un n&uacute;mero variable de par&aacute;metros, aunque s&iacute; soporta - par&aacute;metros por defecto (ver <link - linkend="functions.arguments.default">Valores por defecto de de - los par&aacute;metros</link> para m&aacute;s informaci&oacute;n). PHP4 soporta ambos: ver <link - linkend="functions.variable-arg-list">Listas de longitud variable de - par&aacute;metros</link> y las referencias de las funciones - <function>func_num_args</function>, - <function>func_get_arg</function>, y - <function>func_get_args</function> para m&aacute;s informaci&oacute;n. - </simpara> - - </sect1> - - <sect1 id="functions.arguments"> - <title>Par&aacute;metros de las funciones</title> - - <simpara> - La informaci&oacute;n puede suministrarse a las funciones mediante la lista - de par&aacute;metros, una lista de variables y/o constantes separadas por - comas. - </simpara> - <para> - PHP soporta pasar par&aacute;metros por valor (el comportamiento por defecto), - <link linkend="functions.arguments.by-reference">por referencia</link>, y <link - linkend="functions.arguments.default">par&aacute;metros por defecto</link>. - Listas de longitud variable de par&aacute;metros s&oacute;lo est&aacute;n soportadas en PHP4 y posteriores; - ver <link linkend="functions.variable-arg-list">Listas de longitud variable de par&aacute;metros</link> - y la referencia de las funciones - <function>func_num_args</function>, - <function>func_get_arg</function>, y - <function>func_get_args</function> para m&aacute;s informaci&oacute;n. Un efecto similar puede conseguirse - en PHP3 pasando un array de par&aacute;metros a la funci&oacute;n: - - <informalexample> - <programlisting role="php"> -function takes_array($input) { - echo "$input[0] + $input[1] = ", $input[0]+$input[1]; -} - </programlisting> - </informalexample> - </para> - - <sect2 id="functions.arguments.by-reference"> - <title>Pasar par&aacute;metros por referencia</title> - - <simpara> - Por defecto, los par&aacute;metros de una funci&oacute;n se pasan por valor (de - manera que si cambias el valor del argumento dentro de la funci&oacute;n, no - se ve modificado fuera de ella). Si deseas permitir a una funci&oacute;n - modificar sus par&aacute;metros, debes pasarlos por referencia. - </simpara> - <para> - Si quieres que un par&aacute;metro de una funci&oacute;n siempre se pase por - referencia, puedes anteponer un ampersand (&amp;) al nombre del par&aacute;metro - en la definici&oacute;n de la funci&oacute;n: - - <informalexample> - <programlisting role="php"> -function add_some_extra(&amp;$string) { - $string .= ' y algo m&aacute;s.'; -} -$str = 'Esto es una cadena, '; -add_some_extra($str); -echo $str; // Saca 'Esto es una cadena, y algo m&aacute;s.' - </programlisting> - </informalexample> - </para> - - <para> - Si deseas pasar una variable por referencia a una funci&oacute;n que no - toma el par&aacute;metro por referencia por defecto, puedes anteponer un - ampersand al nombre del par&aacute;metro en la llamada a la funci&oacute;n: - - <informalexample> - <programlisting role="php"> -function foo ($bar) { - $bar .= ' y algo m&aacute;s.'; -} -$str = 'Esto es una cadena, '; -foo ($str); -echo $str; // Saca 'Esto es una cadena, ' -foo (&amp;$str); -echo $str; // Saca 'Esto es una cadena, y algo m&aacute;s.' - </programlisting> - </informalexample> - </para> - - </sect2> - - <sect2 id="functions.arguments.default"> - <title>Par&aacute;metros por defecto</title> - - <para> - Una funci&oacute;n puede definir valores por defecto para los par&aacute;metros - escalares estilo C++: - - <informalexample> - <programlisting role="php"> -function makecoffee ($type = "cappucino") { - return "Hacer una taza de $type.\n"; -} -echo makecoffee (); -echo makecoffee ("espresso"); - </programlisting> - </informalexample> - </para> - - <para> - La salida del fragmento anterior es: - - <screen> -Hacer una taza de cappucino. -Hacer una taza de espresso. - </screen> - </para> - - <simpara> - El valor por defecto tiene que ser una expresi&oacute;n constante, y no - una variable o miembro de una clase. - </simpara> - <para> - En PHP 4.0 tambi&eacute;n es posible especificar <literal>unset</literal> - como par&aacute;metro por defecto. Esto significa que el argumento no tomar&aacute; ning&uacute;n valor - en absoluto si el valor no es suministrado. - </para> - <para> - Destacar que cuando se usan par&aacute;metros por defecto, estos tienen que estar - a la derecha de cualquier par&aacute;metro sin valor por defecto; de otra manera - las cosas no funcionar&aacute;n de la forma esperada. Considera el siguiente fragmento - de c&oacute;digo: - - <informalexample> - <programlisting role="php"> -function makeyogurt ($type = "acidophilus", $flavour) { - return "Haciendo un bol de $type $flavour.\n"; -} - -echo makeyogurt ("mora"); // No funcionar&aacute; de la manera esperada - </programlisting> - </informalexample> - </para> - - <para> - La salida del ejemplo anterior es: - - <screen> -Warning: Missing argument 2 in call to makeyogurt() in -/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41 -Haciendo un bol de mora. - </screen> - </para> - - <para> - Y ahora, comp&aacute;ralo con: - - <informalexample> - <programlisting role="php"> -function makeyogurt ($flavour, $type = "acidophilus") { - return "Haciendo un bol de $type $flavour.\n"; -} - -echo makeyogurt ("mora"); // funciona como se esperaba - </programlisting> - </informalexample> - </para> - - <para> - La salida de este ejemplo es: - - <screen> -Haciendo un bol de acidophilus mora. - </screen> - </para> - - </sect2> - - <sect2 id="functions.variable-arg-list"> - <title>Lista de longitud variable de par&aacute;metros</title> - - <simpara> - PHP4 soporta las listas de longitud variable de par&aacute;metros en las - funciones definidas por el usuario. Es realmente f&aacute;cil, usando - las funciones - <function>func_num_args</function>, - <function>func_get_arg</function>, y - <function>func_get_args</function>. - </simpara> - - <simpara> - No necesita de ninguna sintaxis especial, y las listas de par&aacute;metros - pueden ser escritas en la llamada a la funci&oacute;n y se comportar&aacute;n - de la manera esperada. - </simpara> - - </sect2> - - </sect1> - - <sect1 id="functions.returning-values"> - <title>Devolver valores</title> - - <para> - Los valores se retornan usando la instrucci&oacute;n opcional return. - Puede devolverse cualquier tipo de valor, incluyendo listas y objetos. - - <informalexample> - <programlisting role="php"> -function square ($num) { - return $num * $num; -} -echo square (4); // saca '16'. - </programlisting> - </informalexample> - </para> - - <para> - No puedes devolver m&uacute;ltiples valores desde una funci&oacute;n, pero un - efecto similar se puede conseguir devolviendo una lista. - - <informalexample> - <programlisting role="php"> -function small_numbers() { - return array (0, 1, 2); -} -list ($zero, $one, $two) = small_numbers(); - </programlisting> - </informalexample> - </para> - - </sect1> - - <sect1 id="functions.old-syntax"> - <title><literal>old_function</literal></title> - - <simpara> - La instrucci&oacute;n <literal>old_function</literal> permite declarar una funci&oacute;n usando - una sintaxis id&eacute;ntica a la de PHP/FI2 (excepto que debes reemplazar 'function' - por 'old_function'). - </simpara> - <simpara> - Es una caracter&iacute;stica obsoleta, y deber&iacute;a ser usada &uacute;nicamente por el - conversor PHP/FI2->PHP3. - </simpara> - <warning> - <para> - Las funciones declaradas como <literal>old_function</literal> no pueden llamarse - desde el c&oacute;digo interno de PHP. Entre otras cosas, esto significa que no puedes usarlas - en funciones como <function>usort</function>, <function>array_walk</function>, y - <function>register_shutdown_function</function>. Puedes solventar esta limitaci&oacute;n - escribiendo un "wrapper" (en PHP3 normal) que a su vez llame a la funci&oacute;n declarada como - <literal>old_function</literal>. - </para> - </warning> - - </sect1> - - <sect1 id="functions.variable-functions"> - <title>Funciones variable</title> - - <para> - PHP soporta el concepto de funciones variable, esto significa que si una - variable tiene unos par&eacute;ntesis a&ntilde;adidos al final, PHP buscar&aacute; una funci&oacute;n - con el mismo nombre que la evaluaci&oacute;n de la variable, e intentar&aacute; ejecutarla. - Entre otras cosas, esto te permite implementar retrollamadas (callbacks), - tablas de funciones y dem&aacute;s. - </para> - - <para> - <example> - <title>Ejemplo de funci&oacute;n variable</title> - <programlisting role="php"> -&lt;?php -function foo() { - echo "Dentro de foo()&lt;br>\n"; -} - -function bar( $arg = '' ) { - echo "Dentro de bar(); el par&aacute;metro fue '$arg'.&lt;br>\n"; -} - -$func = 'foo'; -$func(); -$func = 'bar'; -$func( 'test' ); -?> - </programlisting> - </example> - </para> - - </sect1> - - </chapter> - - <!-- Keep this comment at the end of the file - Local variables: - mode: sgml - sgml-omittag:t - sgml-shorttag:t - sgml-minimize-attributes:nil - sgml-always-quote-attributes:t - sgml-indent-step:1 - sgml-indent-data:t - sgml-parent-document:nil - sgml-default-dtd-file:"../../manual.ced" - sgml-exposed-tags:nil - sgml-local-catalogs:nil - sgml-local-ecat-files:nil - End: - --> + <chapter id="functions"> + <title>Funciones</title> + + <sect1 id="functions.user-defined"> + <title>Funciones definidas por el usuario</title> + + <para> + Una funci&oacute;n se define con la siguiente sintaxis: + + <informalexample> + <programlisting role="php"> +function foo ($arg_1, $arg_2, ..., $arg_n) { + echo "Funci&oacute;n de ejemplo.\n"; + return $retval; +} + </programlisting> + </informalexample> + </para> + + <simpara> + Cualquier instrucci&oacute;n v&aacute;lida de PHP puede aparecer en el cuerpo + de la funci&oacute;n, incluso otras funiones y definiciones de + <link linkend="keyword.class">clases</link>. + </simpara> + <simpara> + En PHP3, las funciones deben definirse antes de que se referencien. + En PHP4 no existe tal requerimiento. + </simpara> + <simpara> + PHP no soporta la sobrecarga de funciones, y tampoco es posible + redefinir u ocultar funciones previamente declaradas. + </simpara> + <simpara> + PHP3 no soporta un n&uacute;mero variable de par&aacute;metros, aunque s&iacute; soporta + par&aacute;metros por defecto (ver <link + linkend="functions.arguments.default">Valores por defecto de de + los par&aacute;metros</link> para m&aacute;s informaci&oacute;n). PHP4 soporta ambos: ver <link + linkend="functions.variable-arg-list">Listas de longitud variable de + par&aacute;metros</link> y las referencias de las funciones + <function>func_num_args</function>, + <function>func_get_arg</function>, y + <function>func_get_args</function> para m&aacute;s informaci&oacute;n. + </simpara> + + </sect1> + + <sect1 id="functions.arguments"> + <title>Par&aacute;metros de las funciones</title> + + <simpara> + La informaci&oacute;n puede suministrarse a las funciones mediante la lista + de par&aacute;metros, una lista de variables y/o constantes separadas por + comas. + </simpara> + <para> + PHP soporta pasar par&aacute;metros por valor (el comportamiento por defecto), + <link linkend="functions.arguments.by-reference">por referencia</link>, y <link + linkend="functions.arguments.default">par&aacute;metros por defecto</link>. + Listas de longitud variable de par&aacute;metros s&oacute;lo est&aacute;n soportadas en PHP4 y posteriores; + ver <link linkend="functions.variable-arg-list">Listas de longitud variable de par&aacute;metros</link> + y la referencia de las funciones + <function>func_num_args</function>, + <function>func_get_arg</function>, y + <function>func_get_args</function> para m&aacute;s informaci&oacute;n. Un efecto similar puede conseguirse + en PHP3 pasando un array de par&aacute;metros a la funci&oacute;n: + + <informalexample> + <programlisting role="php"> +function takes_array($input) { + echo "$input[0] + $input[1] = ", $input[0]+$input[1]; +} + </programlisting> + </informalexample> + </para> + + <sect2 id="functions.arguments.by-reference"> + <title>Pasar par&aacute;metros por referencia</title> + + <simpara> + Por defecto, los par&aacute;metros de una funci&oacute;n se pasan por valor (de + manera que si cambias el valor del argumento dentro de la funci&oacute;n, no + se ve modificado fuera de ella). Si deseas permitir a una funci&oacute;n + modificar sus par&aacute;metros, debes pasarlos por referencia. + </simpara> + <para> + Si quieres que un par&aacute;metro de una funci&oacute;n siempre se pase por + referencia, puedes anteponer un ampersand (&amp;) al nombre del par&aacute;metro + en la definici&oacute;n de la funci&oacute;n: + + <informalexample> + <programlisting role="php"> +function add_some_extra(&amp;$string) { + $string .= ' y algo m&aacute;s.'; +} +$str = 'Esto es una cadena, '; +add_some_extra($str); +echo $str; // Saca 'Esto es una cadena, y algo m&aacute;s.' + </programlisting> + </informalexample> + </para> + + <para> + Si deseas pasar una variable por referencia a una funci&oacute;n que no + toma el par&aacute;metro por referencia por defecto, puedes anteponer un + ampersand al nombre del par&aacute;metro en la llamada a la funci&oacute;n: + + <informalexample> + <programlisting role="php"> +function foo ($bar) { + $bar .= ' y algo m&aacute;s.'; +} +$str = 'Esto es una cadena, '; +foo ($str); +echo $str; // Saca 'Esto es una cadena, ' +foo (&amp;$str); +echo $str; // Saca 'Esto es una cadena, y algo m&aacute;s.' + </programlisting> + </informalexample> + </para> + + </sect2> + + <sect2 id="functions.arguments.default"> + <title>Par&aacute;metros por defecto</title> + + <para> + Una funci&oacute;n puede definir valores por defecto para los par&aacute;metros + escalares estilo C++: + + <informalexample> + <programlisting role="php"> +function makecoffee ($type = "cappucino") { + return "Hacer una taza de $type.\n"; +} +echo makecoffee (); +echo makecoffee ("espresso"); + </programlisting> + </informalexample> + </para> + + <para> + La salida del fragmento anterior es: + + <screen> +Hacer una taza de cappucino. +Hacer una taza de espresso. + </screen> + </para> + + <simpara> + El valor por defecto tiene que ser una expresi&oacute;n constante, y no + una variable o miembro de una clase. + </simpara> + <para> + En PHP 4.0 tambi&eacute;n es posible especificar <literal>unset</literal> + como par&aacute;metro por defecto. Esto significa que el argumento no tomar&aacute; ning&uacute;n valor + en absoluto si el valor no es suministrado. + </para> + <para> + Destacar que cuando se usan par&aacute;metros por defecto, estos tienen que estar + a la derecha de cualquier par&aacute;metro sin valor por defecto; de otra manera + las cosas no funcionar&aacute;n de la forma esperada. Considera el siguiente fragmento + de c&oacute;digo: + + <informalexample> + <programlisting role="php"> +function makeyogurt ($type = "acidophilus", $flavour) { + return "Haciendo un bol de $type $flavour.\n"; +} + +echo makeyogurt ("mora"); // No funcionar&aacute; de la manera esperada + </programlisting> + </informalexample> + </para> + + <para> + La salida del ejemplo anterior es: + + <screen> +Warning: Missing argument 2 in call to makeyogurt() in +/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41 +Haciendo un bol de mora. + </screen> + </para> + + <para> + Y ahora, comp&aacute;ralo con: + + <informalexample> + <programlisting role="php"> +function makeyogurt ($flavour, $type = "acidophilus") { + return "Haciendo un bol de $type $flavour.\n"; +} + +echo makeyogurt ("mora"); // funciona como se esperaba + </programlisting> + </informalexample> + </para> + + <para> + La salida de este ejemplo es: + + <screen> +Haciendo un bol de acidophilus mora. + </screen> + </para> + + </sect2> + + <sect2 id="functions.variable-arg-list"> + <title>Lista de longitud variable de par&aacute;metros</title> + + <simpara> + PHP4 soporta las listas de longitud variable de par&aacute;metros en las + funciones definidas por el usuario. Es realmente f&aacute;cil, usando + las funciones + <function>func_num_args</function>, + <function>func_get_arg</function>, y + <function>func_get_args</function>. + </simpara> + + <simpara> + No necesita de ninguna sintaxis especial, y las listas de par&aacute;metros + pueden ser escritas en la llamada a la funci&oacute;n y se comportar&aacute;n + de la manera esperada. + </simpara> + + </sect2> + + </sect1> + + <sect1 id="functions.returning-values"> + <title>Devolver valores</title> + + <para> + Los valores se retornan usando la instrucci&oacute;n opcional return. + Puede devolverse cualquier tipo de valor, incluyendo listas y objetos. + + <informalexample> + <programlisting role="php"> +function square ($num) { + return $num * $num; +} +echo square (4); // saca '16'. + </programlisting> + </informalexample> + </para> + + <para> + No puedes devolver m&uacute;ltiples valores desde una funci&oacute;n, pero un + efecto similar se puede conseguir devolviendo una lista. + + <informalexample> + <programlisting role="php"> +function small_numbers() { + return array (0, 1, 2); +} +list ($zero, $one, $two) = small_numbers(); + </programlisting> + </informalexample> + </para> + + </sect1> + + <sect1 id="functions.old-syntax"> + <title><literal>old_function</literal></title> + + <simpara> + La instrucci&oacute;n <literal>old_function</literal> permite declarar una funci&oacute;n usando + una sintaxis id&eacute;ntica a la de PHP/FI2 (excepto que debes reemplazar 'function' + por 'old_function'). + </simpara> + <simpara> + Es una caracter&iacute;stica obsoleta, y deber&iacute;a ser usada &uacute;nicamente por el + conversor PHP/FI2->PHP3. + </simpara> + <warning> + <para> + Las funciones declaradas como <literal>old_function</literal> no pueden llamarse + desde el c&oacute;digo interno de PHP. Entre otras cosas, esto significa que no puedes usarlas + en funciones como <function>usort</function>, <function>array_walk</function>, y + <function>register_shutdown_function</function>. Puedes solventar esta limitaci&oacute;n + escribiendo un "wrapper" (en PHP3 normal) que a su vez llame a la funci&oacute;n declarada como + <literal>old_function</literal>. + </para> + </warning> + + </sect1> + + <sect1 id="functions.variable-functions"> + <title>Funciones variable</title> + + <para> + PHP soporta el concepto de funciones variable, esto significa que si una + variable tiene unos par&eacute;ntesis a&ntilde;adidos al final, PHP buscar&aacute; una funci&oacute;n + con el mismo nombre que la evaluaci&oacute;n de la variable, e intentar&aacute; ejecutarla. + Entre otras cosas, esto te permite implementar retrollamadas (callbacks), + tablas de funciones y dem&aacute;s. + </para> + + <para> + <example> + <title>Ejemplo de funci&oacute;n variable</title> + <programlisting role="php"> +&lt;?php +function foo() { + echo "Dentro de foo()&lt;br>\n"; +} + +function bar( $arg = '' ) { + echo "Dentro de bar(); el par&aacute;metro fue '$arg'.&lt;br>\n"; +} + +$func = 'foo'; +$func(); +$func = 'bar'; +$func( 'test' ); +?> + </programlisting> + </example> + </para> + + </sect1> + + </chapter> + + <!-- Keep this comment at the end of the file + Local variables: + mode: sgml + sgml-omittag:t + sgml-shorttag:t + sgml-minimize-attributes:nil + sgml-always-quote-attributes:t + sgml-indent-step:1 + sgml-indent-data:t + sgml-parent-document:nil + sgml-default-dtd-file:"../../manual.ced" + sgml-exposed-tags:nil + sgml-local-catalogs:nil + sgml-local-ecat-files:nil + End: + --> Index: phpdoc/es/language/operators.xml diff -u phpdoc/es/language/operators.xml:1.2 phpdoc/es/language/operators.xml:1.3 --- phpdoc/es/language/operators.xml:1.2 Thu Aug 24 02:51:15 2000 +++ phpdoc/es/language/operators.xml Sat Jul 7 19:11:27 2001 @@ -1,542 +1,542 @@ - <chapter id="language.operators"> - <title>Operadores</title> - <simpara> - </simpara> - - <sect1 id="language.operators.arithmetic"> - <title>Operadores Aritm&eacute;ticos</title> - <simpara> - ¿Recuerdas la aritm&eacute;tica b&aacute;sica del colegio? Pues estos operadores - funcionan exactamente igual. - </simpara> - - <table> - <title>Operadores Aritm&eacute;ticos</title> - <tgroup cols="3"> - <thead> - <row> - <entry>ejemplo</entry> - <entry>nombre</entry> - <entry>resultado</entry> - </row> - </thead> - <tbody> - <row> - <entry>$a + $b</entry> - <entry>Adici&oacute;n</entry> - <entry>Suma de $a y $b.</entry> - </row> - <row> - <entry>$a - $b</entry> - <entry>Substracci&oacute;n</entry> - <entry>Diferencia entre $a y $b.</entry> - </row> - <row> - <entry>$a * $b</entry> - <entry>Multiplicaci&oacute;n</entry> - <entry>Producto de $a and $b.</entry> - </row> - <row> - <entry>$a / $b</entry> - <entry>Divisi&oacute;n</entry> - <entry>Cociente de $a entre $b.</entry> - </row> - <row> - <entry>$a % $b</entry> - <entry>M&oacute;dulo</entry> - <entry>Resto de $a dividido entre $b.</entry> - </row> - </tbody> - </tgroup> - </table> - -<!-- Esto parece no ajustarse a la realidad. La divisi&oacute;n siempre devuelve un valor en punto flotante. - <simpara> - El operador de divisi&oacute;n ("/") devuelve un entero (el resultado de la - divisi&oacute;n entera) si los dos operandos son enteros (o cadenas que se - han convertido a enteros). Si alguno de los operandos es un valor - en punto flotante, se realiza la divisi&oacute;n en punto flotante. - </simpara> ---></sect1> - - <sect1 id="language.operators.assignment"> - <title>Operadores de Asignaci&oacute;n</title> - <simpara> - El operador b&aacute;sico de asignaci&oacute;n es "=". A primera vista podr&iacute;as - pensar que es el operador de comparaci&oacute;n "igual que". Pero no. Realmente - significa que el operando de la izquierda toma el valor de la expresi&oacute;n a la derecha, - (esto es, "toma el valor de"). - </simpara> - <para> - El valor de una expresi&oacute;n de asignaci&oacute;n es el propio valor asignado. - Esto es, el valor de "$a = 3" es 3. Esto permite hacer cosas curiosas como - <informalexample><programlisting> -$a = ($b = 4) + 5; // ahora $a es igual a 9, y $b vale 4. -</programlisting></informalexample> - </para> - <para> - Adem&aacute;s del operador b&aacute;sico de asignaci&oacute;n, existen los "operadores combinados" - para todas las operaciones aritm&eacute;ticas y de cadenas que sean binarias. Este - operador combinado te permite, de una sola vez, usar una variable - en una expresi&oacute;n y luego establecer el valor de esa variable al - resultado de la expresi&oacute;n. Por ejemplo: <informalexample><programlisting> -$a = 3; -$a += 5; // establece $a a 8, como si hubi&eacute;semos escrito: $a = $a + 5; -$b = "Hola "; -$b .= "Ah&iacute;!"; // establece $b a "Hola Ah&iacute;!", igual que si hici&eacute;semos $b = $b . "Ah&iacute;!"; -</programlisting></informalexample> - </para> - - <para> - F&iacute;jate en que la asignaci&oacute;n realiza una nueva copia de la variable original - (asignaci&oacute;n por valor), por lo que cambios a la variable original no afectan a la copia. - Esto puede tener inter&eacute;s si necesitas copiar algo como un array con muchos elementos - dentro de un bucle que se repita muchas veces (cada vez se realizar&aacute; una nueva copia del array). - PHP4 soporta asignaci&oacute;n por referencia, usando - la sintaxis <computeroutput>$var = &amp;$othervar;</computeroutput>, - pero esto no es posible en PHP3. 'Asignaci&oacute;n por referencia' - quiere decir que ambas variables acabar&aacute;n apuntando al mismo dato y - que nada es realmente copiado. - </para> - - </sect1> - - <sect1 id="language.operators.bitwise"> - <title>Operadores Bit a bit</title> - <simpara> - Los operadores bit a bit te permiten activar o desactivar bits - individuales de un entero. - </simpara> - - <table> - <title>Operadores Bit a bit</title> - <tgroup cols="3"> - <thead> - <row> - <entry>ejemplo</entry> - <entry>nombre</entry> - <entry>resultado</entry> - </row> - </thead> - <tbody> - <row> - <entry>$a & $b</entry> - <entry>Y</entry> - <entry>Se activan los bits que est&aacute;n activos tanto en $a como $b.</entry> - </row> - <row> - <entry>$a | $b</entry> - <entry>O</entry> - <entry>Se activan los bits que est&aacute;n activos en $a o que lo est&aacute;n en $b.</entry> - </row> - <row> - <entry>$a ^ $b</entry> - <entry>Xor ("o exclusiva")</entry> - <entry>Se activan los bits que est&aacute;n activos en $a o en $b pero no en ambos a la vez.</entry> - </row> - <row> - <entry>~ $a</entry> - <entry>No</entry> - <entry>Se activan los bits que no est&aacute;n activos en $a.</entry> - </row> - <row> - <entry>$a &lt;&lt; $b</entry> - <entry>Desplazamiento a la izquierda</entry> - <entry>Desplaza los bits de $a, $b posiciones hacia la izquierda (por aritm&eacute;tica binaria, cada posici&oacute;n - desplazada equivale a multiplicar por dos el valor de $a)</entry> - </row> - <row> - <entry>$a &gt;&gt; $b</entry> - <entry>Desplazamiento a la derecha</entry> - <entry>Desplaza los bits de $a, $b posiciones hacia la derecha (por aritm&eacute;tica binaria, cada posici&oacute;n - desplazada equivale a dividir entre dos el valor de $a)</entry> - </row> - </tbody> - </tgroup> - </table> - </sect1> - - - - <sect1 id="language.operators.comparison"> - <title>Operadores de Comparaci&oacute;n</title> - <simpara> - Los operadores de comparaci&oacute;n, como su nombre indica, permiten comparar dos valores. - </simpara> - - <table> - <title>Operadores de Comparaci&oacute;n</title> - <tgroup cols="3"> - <thead> - <row> - <entry>ejemplo</entry> - <entry>nombre</entry> - <entry>resultado</entry> - </row> - </thead> - <tbody> - <row> - <entry>$a == $b</entry> - <entry>Igualdad</entry> - <entry>Cierto si $a es igual a $b.</entry> - </row> - <row> - <entry>$a === $b</entry> - <entry>Identidad</entry> - <entry>Cierto si $a es igual a $b y si son del mismo tipo (s&oacute;lo PHP4)</entry> - </row> - <row> - <entry>$a != $b</entry> - <entry>Desigualdad</entry> - <entry>Cierto si $a no es igual a $b.</entry> - </row> - <row> - <entry>$a &lt; $b</entry> - <entry>Menor que</entry> - <entry>Cierto si $a es estrictamente menor que $b.</entry> - </row> - <row> - <entry>$a &gt; $b</entry> - <entry>Mayor que</entry> - <entry>Cierto si $a es estrictamente mayor que $b.</entry> - </row> - <row> - <entry>$a &lt;= $b</entry> - <entry>Menor o igual que</entry> - <entry>Cierto si $a es menor o igual que $b.</entry> - </row> - <row> - <entry>$a &gt;= $b</entry> - <entry>Mayor o igual que</entry> - <entry>Cierto si $a es mayor o igual que $b.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - Otro operador condicional es el operador "?:" (o ternario), - que funciona como en C y otros muchos lenguajes. - - <informalexample> - <programlisting> -(expr1) ? (expr2) : (expr3); - </programlisting> - </informalexample> - - La expresi&oacute;n toma el valor <replaceable>expr2</replaceable> si - <replaceable>expr1</replaceable> se eval&uacute;a a cierto, y - <replaceable>expr3</replaceable> si - <replaceable>expr1</replaceable> se eval&uacute;a a falso. - </para> - </sect1> - - - <sect1 id="language.operators.execution"> - <title>Operador de ejecuci&oacute;n</title> - - <para> - PHP soporta un operador de ejecuci&oacute;n: el ap&oacute;strofe invertido (``). ¡F&iacute;jate - que no son apostrofes normales! - PHP intentar&aacute; ejecutar la instrucci&oacute;n contenida dentro de los ap&oacute;strofes - invertidos como si fuera un comando del shell; y su salida devuelta como - el valor de esta expresi&oacute;n (i.e., no tiene por qu&eacute; ser simplemente volcada - como salida; puede asignarse a una variable). - - <informalexample> - <programlisting role="php"> -$output = `ls -al`; -echo "&lt;pre&gt;$output&lt;/pre&gt;"; - </programlisting> - </informalexample> - - </para> - - <para> - Ver tambi&eacute;n <function>system</function>, - <function>passthru</function>, <function>exec</function>, - <function>popen</function>, y - <function>escapeshellcmd</function>. - </para> - - </sect1> - - - <sect1 id="language.operators.increment"> - <title>Operadores de Incremento/decremento</title> - - <para> - PHP soporta los operadores de predecremento y post incremento - al estilo de C. - </para> - - <table> - <title>Operadores de Incremento/decremento</title> - <tgroup cols="3"> - <thead> - <row> - <entry>ejemplo</entry> - <entry>nombre</entry> - <entry>efecto</entry> - </row> - </thead> - <tbody> - <row> - <entry>++$a</entry> - <entry>Preincremento</entry> - <entry>Incrementa $a en uno y despu&eacute;s devuelve $a.</entry> - </row> - <row> - <entry>$a++</entry> - <entry>Postincremento</entry> - <entry>Devuelve $a y despu&eacute;s incrementa $a en uno.</entry> - </row> - <row> - <entry>--$a</entry> - <entry>Predecremento</entry> - <entry>Decrementa $a en uno y despu&eacute;s devuelve $a.</entry> - </row> - <row> - <entry>$a--</entry> - <entry>Postdecremento</entry> - <entry>Devuelve $a y despu&eacute;s decrementa $a en uno.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - He aqu&iacute; un listado de ejemplo: - <informalexample> - <programlisting> -&lt;?php -echo "&lt;h3&gt;Postincremento&lt;/h3&gt;"; -$a = 5; -echo "Deber&iacute;a ser 5: " . $a++ . "&lt;br&gt;\n"; -echo "Deber&iacute;a ser 6: " . $a . "&lt;br&gt;\n"; - -echo "&lt;h3&gt;Preincremento&lt;/h3&gt;"; -$a = 5; -echo "Deber&iacute;a ser 6: " . ++$a . "&lt;br&gt;\n"; -echo "Deber&iacute;a ser 6: " . $a . "&lt;br&gt;\n"; - -echo "&lt;h3&gt;Postdecremento&lt;/h3&gt;"; -$a = 5; -echo "Deber&iacute;a ser 5: " . $a-- . "&lt;br&gt;\n"; -echo "Deber&iacute;a ser 4: " . $a . "&lt;br&gt;\n"; - -echo "&lt;h3&gt;Predecremento&lt;/h3&gt;"; -$a = 5; -echo "Deber&iacute;a ser 4: " . --$a . "&lt;br&gt;\n"; -echo "Deber&iacute;a ser 4: " . $a . "&lt;br&gt;\n"; -?&gt; - </programlisting> - </informalexample> - </para> - - </sect1> - - - <sect1 id="language.operators.logical"> - <title>Operadores L&oacute;gicos</title> - - <table> - <title>Operadores L&oacute;gicos</title> - <tgroup cols="3"> - <thead> - <row> - <entry>ejemplo</entry> - <entry>nombre</entry> - <entry>resultado</entry> - </row> - </thead> - <tbody> - <row> - <entry>$a and $b</entry> - <entry>Y</entry> - <entry>Cierto si tanto $a como $b son ciertos.</entry> - </row> - <row> - <entry>$a or $b</entry> - <entry>O</entry> - <entry>Cierto si $a o $b son ciertos.</entry> - </row> - <row> - <entry>$a xor $b</entry> - <entry>O exclusiva</entry> - <entry>Cierto si $a es cierto o $b es cierto, pero no ambos a la vez.</entry> - </row> - <row> - <entry>! $a</entry> - <entry>Negaci&oacute;n</entry> - <entry>Cierto si $a no es cierto.</entry> - </row> - <row> - <entry>$a &amp;&amp; $b</entry> - <entry>Y</entry> - <entry>Cierto si tanto $a como $b son ciertos.</entry> - </row> - <row> - <entry>$a || $b</entry> - <entry>O</entry> - <entry>Cierto si $a o $b son ciertos.</entry> - </row> - </tbody> - </tgroup> - </table> - - <simpara> - La raz&oacute;n de las dos variaciones de "y" y "o" es que operan con - distinta precedencia (ver <link linkend="language.operators.precedence">Precedencia - de Operadores</link>.) - </simpara> - </sect1> - - <sect1 id="language.operators.precedence"> - <title>Precedencia de Operadores</title> - <para> - La precedencia de operadores especifica c&oacute;mo se agrupan las expresiones. - Por ejemplo, en la expresi&oacute;n - <literal>1 + 5 * 3</literal>, la respuesta es 16 y no 18 porque el - operador de multiplicaci&oacute;n ("*") tiene una mayor precedencia - que el de adici&oacute;n ("+").</para> - <para> - La siguiente tabla lista la precedencia de operadores, indic&aacute;ndose - primero los de menor precedencia. - - <table> - <title>Precedencia de Operadores</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Asociatividad</entry> - <entry>Operadores</entry> - </row> - </thead> - <tbody> - <row> - <entry>izquierda</entry> - <entry>,</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>or</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>xor</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>and</entry> - </row> - <row> - <entry>derecha</entry> - <entry>print</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>= += -= *= /= .= %= &= |= ^= ~= &lt;&lt;= &gt;&gt;=</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>? :</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>||</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>&amp;&amp;</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>|</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>^</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>&amp;</entry> - </row> - <row> - <entry>no asociativo</entry> - <entry>== != ===</entry> - </row> - <row> - <entry>no asociativo</entry> - <entry>&lt; &lt;= &gt; &gt;=</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>&lt;&lt; &gt;&gt;</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>+ - .</entry> - </row> - <row> - <entry>izquierda</entry> - <entry>* / %</entry> - </row> - <row> - <entry>derecha</entry> - <entry>! ~ ++ -- (int) (double) (string) (array) (object) @</entry> - </row> - <row> - <entry>derecha</entry> - <entry>[</entry> - </row> - <row> - <entry>no asociativo</entry> - <entry>new</entry> - </row> - </tbody> - </tgroup> - </table></para></sect1> - - <sect1 id="language.operators.string"> - <title>Operadores de Cadenas</title> - <simpara> - Hay dos operadores de cadenas. El primero es el operador de - concatenaci&oacute;n ('.'), que devuelve el resultado de concatenar sus - operandos izquierdo y derecho. El segundo es el operador de concatenaci&oacute;n - y asignaci&oacute;n ('.='). Consulta <link - linkend="language.operators.assignment">Operadores de - Asignaci&oacute;n</link> para m&aacute;s informaci&oacute;n. - </simpara> - <para> - <informalexample> - <programlisting> -$a = "Hola "; -$b = $a . "Mundo!"; // ahora $b contiene "Hola Mundo!" - -$a = "Hola "; -$a .= "Mundo!"; // ahora $a contiene "Hola Mundo!" - </programlisting> - </informalexample> - </para> - </sect1> - - - </chapter> - - <!-- Keep this comment at the end of the file - Local variables: - mode: sgml - sgml-omittag:t - sgml-shorttag:t - sgml-minimize-attributes:nil - sgml-always-quote-attributes:t - sgml-indent-step:1 - sgml-indent-data:t - sgml-parent-document:nil - sgml-default-dtd-file:"../manual.ced" - sgml-exposed-tags:nil - sgml-local-catalogs:nil - sgml-local-ecat-files:nil - End: - --> + <chapter id="language.operators"> + <title>Operadores</title> + <simpara> + </simpara> + + <sect1 id="language.operators.arithmetic"> + <title>Operadores Aritm&eacute;ticos</title> + <simpara> + ¿Recuerdas la aritm&eacute;tica b&aacute;sica del colegio? Pues estos operadores + funcionan exactamente igual. + </simpara> + + <table> + <title>Operadores Aritm&eacute;ticos</title> + <tgroup cols="3"> + <thead> + <row> + <entry>ejemplo</entry> + <entry>nombre</entry> + <entry>resultado</entry> + </row> + </thead> + <tbody> + <row> + <entry>$a + $b</entry> + <entry>Adici&oacute;n</entry> + <entry>Suma de $a y $b.</entry> + </row> + <row> + <entry>$a - $b</entry> + <entry>Substracci&oacute;n</entry> + <entry>Diferencia entre $a y $b.</entry> + </row> + <row> + <entry>$a * $b</entry> + <entry>Multiplicaci&oacute;n</entry> + <entry>Producto de $a and $b.</entry> + </row> + <row> + <entry>$a / $b</entry> + <entry>Divisi&oacute;n</entry> + <entry>Cociente de $a entre $b.</entry> + </row> + <row> + <entry>$a % $b</entry> + <entry>M&oacute;dulo</entry> + <entry>Resto de $a dividido entre $b.</entry> + </row> + </tbody> + </tgroup> + </table> + +<!-- Esto parece no ajustarse a la realidad. La divisi&oacute;n siempre devuelve un valor en punto flotante. + <simpara> + El operador de divisi&oacute;n ("/") devuelve un entero (el resultado de la + divisi&oacute;n entera) si los dos operandos son enteros (o cadenas que se + han convertido a enteros). Si alguno de los operandos es un valor + en punto flotante, se realiza la divisi&oacute;n en punto flotante. + </simpara> +--></sect1> + + <sect1 id="language.operators.assignment"> + <title>Operadores de Asignaci&oacute;n</title> + <simpara> + El operador b&aacute;sico de asignaci&oacute;n es "=". A primera vista podr&iacute;as + pensar que es el operador de comparaci&oacute;n "igual que". Pero no. Realmente + significa que el operando de la izquierda toma el valor de la expresi&oacute;n a la derecha, + (esto es, "toma el valor de"). + </simpara> + <para> + El valor de una expresi&oacute;n de asignaci&oacute;n es el propio valor asignado. + Esto es, el valor de "$a = 3" es 3. Esto permite hacer cosas curiosas como + <informalexample><programlisting> +$a = ($b = 4) + 5; // ahora $a es igual a 9, y $b vale 4. +</programlisting></informalexample> + </para> + <para> + Adem&aacute;s del operador b&aacute;sico de asignaci&oacute;n, existen los "operadores combinados" + para todas las operaciones aritm&eacute;ticas y de cadenas que sean binarias. Este + operador combinado te permite, de una sola vez, usar una variable + en una expresi&oacute;n y luego establecer el valor de esa variable al + resultado de la expresi&oacute;n. Por ejemplo: <informalexample><programlisting> +$a = 3; +$a += 5; // establece $a a 8, como si hubi&eacute;semos escrito: $a = $a + 5; +$b = "Hola "; +$b .= "Ah&iacute;!"; // establece $b a "Hola Ah&iacute;!", igual que si hici&eacute;semos $b = $b . "Ah&iacute;!"; +</programlisting></informalexample> + </para> + + <para> + F&iacute;jate en que la asignaci&oacute;n realiza una nueva copia de la variable original + (asignaci&oacute;n por valor), por lo que cambios a la variable original no afectan a la copia. + Esto puede tener inter&eacute;s si necesitas copiar algo como un array con muchos elementos + dentro de un bucle que se repita muchas veces (cada vez se realizar&aacute; una nueva copia del array). + PHP4 soporta asignaci&oacute;n por referencia, usando + la sintaxis <computeroutput>$var = &amp;$othervar;</computeroutput>, + pero esto no es posible en PHP3. 'Asignaci&oacute;n por referencia' + quiere decir que ambas variables acabar&aacute;n apuntando al mismo dato y + que nada es realmente copiado. + </para> + + </sect1> + + <sect1 id="language.operators.bitwise"> + <title>Operadores Bit a bit</title> + <simpara> + Los operadores bit a bit te permiten activar o desactivar bits + individuales de un entero. + </simpara> + + <table> + <title>Operadores Bit a bit</title> + <tgroup cols="3"> + <thead> + <row> + <entry>ejemplo</entry> + <entry>nombre</entry> + <entry>resultado</entry> + </row> + </thead> + <tbody> + <row> + <entry>$a & $b</entry> + <entry>Y</entry> + <entry>Se activan los bits que est&aacute;n activos tanto en $a como $b.</entry> + </row> + <row> + <entry>$a | $b</entry> + <entry>O</entry> + <entry>Se activan los bits que est&aacute;n activos en $a o que lo est&aacute;n en $b.</entry> + </row> + <row> + <entry>$a ^ $b</entry> + <entry>Xor ("o exclusiva")</entry> + <entry>Se activan los bits que est&aacute;n activos en $a o en $b pero no en ambos a la vez.</entry> + </row> + <row> + <entry>~ $a</entry> + <entry>No</entry> + <entry>Se activan los bits que no est&aacute;n activos en $a.</entry> + </row> + <row> + <entry>$a &lt;&lt; $b</entry> + <entry>Desplazamiento a la izquierda</entry> + <entry>Desplaza los bits de $a, $b posiciones hacia la izquierda (por aritm&eacute;tica binaria, cada posici&oacute;n + desplazada equivale a multiplicar por dos el valor de $a)</entry> + </row> + <row> + <entry>$a &gt;&gt; $b</entry> + <entry>Desplazamiento a la derecha</entry> + <entry>Desplaza los bits de $a, $b posiciones hacia la derecha (por aritm&eacute;tica binaria, cada posici&oacute;n + desplazada equivale a dividir entre dos el valor de $a)</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + + + <sect1 id="language.operators.comparison"> + <title>Operadores de Comparaci&oacute;n</title> + <simpara> + Los operadores de comparaci&oacute;n, como su nombre indica, permiten comparar dos valores. + </simpara> + + <table> + <title>Operadores de Comparaci&oacute;n</title> + <tgroup cols="3"> + <thead> + <row> + <entry>ejemplo</entry> + <entry>nombre</entry> + <entry>resultado</entry> + </row> + </thead> + <tbody> + <row> + <entry>$a == $b</entry> + <entry>Igualdad</entry> + <entry>Cierto si $a es igual a $b.</entry> + </row> + <row> + <entry>$a === $b</entry> + <entry>Identidad</entry> + <entry>Cierto si $a es igual a $b y si son del mismo tipo (s&oacute;lo PHP4)</entry> + </row> + <row> + <entry>$a != $b</entry> + <entry>Desigualdad</entry> + <entry>Cierto si $a no es igual a $b.</entry> + </row> + <row> + <entry>$a &lt; $b</entry> + <entry>Menor que</entry> + <entry>Cierto si $a es estrictamente menor que $b.</entry> + </row> + <row> + <entry>$a &gt; $b</entry> + <entry>Mayor que</entry> + <entry>Cierto si $a es estrictamente mayor que $b.</entry> + </row> + <row> + <entry>$a &lt;= $b</entry> + <entry>Menor o igual que</entry> + <entry>Cierto si $a es menor o igual que $b.</entry> + </row> + <row> + <entry>$a &gt;= $b</entry> + <entry>Mayor o igual que</entry> + <entry>Cierto si $a es mayor o igual que $b.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Otro operador condicional es el operador "?:" (o ternario), + que funciona como en C y otros muchos lenguajes. + + <informalexample> + <programlisting> +(expr1) ? (expr2) : (expr3); + </programlisting> + </informalexample> + + La expresi&oacute;n toma el valor <replaceable>expr2</replaceable> si + <replaceable>expr1</replaceable> se eval&uacute;a a cierto, y + <replaceable>expr3</replaceable> si + <replaceable>expr1</replaceable> se eval&uacute;a a falso. + </para> + </sect1> + + + <sect1 id="language.operators.execution"> + <title>Operador de ejecuci&oacute;n</title> + + <para> + PHP soporta un operador de ejecuci&oacute;n: el ap&oacute;strofe invertido (``). ¡F&iacute;jate + que no son apostrofes normales! + PHP intentar&aacute; ejecutar la instrucci&oacute;n contenida dentro de los ap&oacute;strofes + invertidos como si fuera un comando del shell; y su salida devuelta como + el valor de esta expresi&oacute;n (i.e., no tiene por qu&eacute; ser simplemente volcada + como salida; puede asignarse a una variable). + + <informalexample> + <programlisting role="php"> +$output = `ls -al`; +echo "&lt;pre&gt;$output&lt;/pre&gt;"; + </programlisting> + </informalexample> + + </para> + + <para> + Ver tambi&eacute;n <function>system</function>, + <function>passthru</function>, <function>exec</function>, + <function>popen</function>, y + <function>escapeshellcmd</function>. + </para> + + </sect1> + + + <sect1 id="language.operators.increment"> + <title>Operadores de Incremento/decremento</title> + + <para> + PHP soporta los operadores de predecremento y post incremento + al estilo de C. + </para> + + <table> + <title>Operadores de Incremento/decremento</title> + <tgroup cols="3"> + <thead> + <row> + <entry>ejemplo</entry> + <entry>nombre</entry> + <entry>efecto</entry> + </row> + </thead> + <tbody> + <row> + <entry>++$a</entry> + <entry>Preincremento</entry> + <entry>Incrementa $a en uno y despu&eacute;s devuelve $a.</entry> + </row> + <row> + <entry>$a++</entry> + <entry>Postincremento</entry> + <entry>Devuelve $a y despu&eacute;s incrementa $a en uno.</entry> + </row> + <row> + <entry>--$a</entry> + <entry>Predecremento</entry> + <entry>Decrementa $a en uno y despu&eacute;s devuelve $a.</entry> + </row> + <row> + <entry>$a--</entry> + <entry>Postdecremento</entry> + <entry>Devuelve $a y despu&eacute;s decrementa $a en uno.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + He aqu&iacute; un listado de ejemplo: + <informalexample> + <programlisting> +&lt;?php +echo "&lt;h3&gt;Postincremento&lt;/h3&gt;"; +$a = 5; +echo "Deber&iacute;a ser 5: " . $a++ . "&lt;br&gt;\n"; +echo "Deber&iacute;a ser 6: " . $a . "&lt;br&gt;\n"; + +echo "&lt;h3&gt;Preincremento&lt;/h3&gt;"; +$a = 5; +echo "Deber&iacute;a ser 6: " . ++$a . "&lt;br&gt;\n"; +echo "Deber&iacute;a ser 6: " . $a . "&lt;br&gt;\n"; + +echo "&lt;h3&gt;Postdecremento&lt;/h3&gt;"; +$a = 5; +echo "Deber&iacute;a ser 5: " . $a-- . "&lt;br&gt;\n"; +echo "Deber&iacute;a ser 4: " . $a . "&lt;br&gt;\n"; + +echo "&lt;h3&gt;Predecremento&lt;/h3&gt;"; +$a = 5; +echo "Deber&iacute;a ser 4: " . --$a . "&lt;br&gt;\n"; +echo "Deber&iacute;a ser 4: " . $a . "&lt;br&gt;\n"; +?&gt; + </programlisting> + </informalexample> + </para> + + </sect1> + + + <sect1 id="language.operators.logical"> + <title>Operadores L&oacute;gicos</title> + + <table> + <title>Operadores L&oacute;gicos</title> + <tgroup cols="3"> + <thead> + <row> + <entry>ejemplo</entry> + <entry>nombre</entry> + <entry>resultado</entry> + </row> + </thead> + <tbody> + <row> + <entry>$a and $b</entry> + <entry>Y</entry> + <entry>Cierto si tanto $a como $b son ciertos.</entry> + </row> + <row> + <entry>$a or $b</entry> + <entry>O</entry> + <entry>Cierto si $a o $b son ciertos.</entry> + </row> + <row> + <entry>$a xor $b</entry> + <entry>O exclusiva</entry> + <entry>Cierto si $a es cierto o $b es cierto, pero no ambos a la vez.</entry> + </row> + <row> + <entry>! $a</entry> + <entry>Negaci&oacute;n</entry> + <entry>Cierto si $a no es cierto.</entry> + </row> + <row> + <entry>$a &amp;&amp; $b</entry> + <entry>Y</entry> + <entry>Cierto si tanto $a como $b son ciertos.</entry> + </row> + <row> + <entry>$a || $b</entry> + <entry>O</entry> + <entry>Cierto si $a o $b son ciertos.</entry> + </row> + </tbody> + </tgroup> + </table> + + <simpara> + La raz&oacute;n de las dos variaciones de "y" y "o" es que operan con + distinta precedencia (ver <link linkend="language.operators.precedence">Precedencia + de Operadores</link>.) + </simpara> + </sect1> + + <sect1 id="language.operators.precedence"> + <title>Precedencia de Operadores</title> + <para> + La precedencia de operadores especifica c&oacute;mo se agrupan las expresiones. + Por ejemplo, en la expresi&oacute;n + <literal>1 + 5 * 3</literal>, la respuesta es 16 y no 18 porque el + operador de multiplicaci&oacute;n ("*") tiene una mayor precedencia + que el de adici&oacute;n ("+").</para> + <para> + La siguiente tabla lista la precedencia de operadores, indic&aacute;ndose + primero los de menor precedencia. + + <table> + <title>Precedencia de Operadores</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Asociatividad</entry> + <entry>Operadores</entry> + </row> + </thead> + <tbody> + <row> + <entry>izquierda</entry> + <entry>,</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>or</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>xor</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>and</entry> + </row> + <row> + <entry>derecha</entry> + <entry>print</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>= += -= *= /= .= %= &= |= ^= ~= &lt;&lt;= &gt;&gt;=</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>? :</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>||</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>&amp;&amp;</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>|</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>^</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>&amp;</entry> + </row> + <row> + <entry>no asociativo</entry> + <entry>== != ===</entry> + </row> + <row> + <entry>no asociativo</entry> + <entry>&lt; &lt;= &gt; &gt;=</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>&lt;&lt; &gt;&gt;</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>+ - .</entry> + </row> + <row> + <entry>izquierda</entry> + <entry>* / %</entry> + </row> + <row> + <entry>derecha</entry> + <entry>! ~ ++ -- (int) (double) (string) (array) (object) @</entry> + </row> + <row> + <entry>derecha</entry> + <entry>[</entry> + </row> + <row> + <entry>no asociativo</entry> + <entry>new</entry> + </row> + </tbody> + </tgroup> + </table></para></sect1> + + <sect1 id="language.operators.string"> + <title>Operadores de Cadenas</title> + <simpara> + Hay dos operadores de cadenas. El primero es el operador de + concatenaci&oacute;n ('.'), que devuelve el resultado de concatenar sus + operandos izquierdo y derecho. El segundo es el operador de concatenaci&oacute;n + y asignaci&oacute;n ('.='). Consulta <link + linkend="language.operators.assignment">Operadores de + Asignaci&oacute;n</link> para m&aacute;s informaci&oacute;n. + </simpara> + <para> + <informalexample> + <programlisting> +$a = "Hola "; +$b = $a . "Mundo!"; // ahora $b contiene "Hola Mundo!" + +$a = "Hola "; +$a .= "Mundo!"; // ahora $a contiene "Hola Mundo!" + </programlisting> + </informalexample> + </para> + </sect1> + + + </chapter> + + <!-- Keep this comment at the end of the file + Local variables: + mode: sgml + sgml-omittag:t + sgml-shorttag:t + sgml-minimize-attributes:nil + sgml-always-quote-attributes:t + sgml-indent-step:1 + sgml-indent-data:t + sgml-parent-document:nil + sgml-default-dtd-file:"../manual.ced" + sgml-exposed-tags:nil + sgml-local-catalogs:nil + sgml-local-ecat-files:nil + End: + --> Index: phpdoc/fr/functions/bzip2.xml diff -u phpdoc/fr/functions/bzip2.xml:1.9 phpdoc/fr/functions/bzip2.xml:1.10 --- phpdoc/fr/functions/bzip2.xml:1.9 Sat Jul 7 18:22:01 2001 +++ phpdoc/fr/functions/bzip2.xml Sat Jul 7 19:11:29 2001 @@ -1 +1,441 @@ - <reference id="ref.bzip2"> <title>Compression Bzip2</title> <titleabbrev>Bzip2</titleabbrev> <partintro> <para> Ce module utilise les fonctions de la librairie <ulink url="&url.bzip2;">bzip2</ulink>, de Julian Seward pour &eacute;crire et lire des fichier bzip2 (.bz2) de mani&egrave;re transparente. </para> <para> Le support <acronym>bzip2</acronym> par PHP n'est pas activ&eacute; par d&eacute;faut. Vous devez utiliser l'option de configuration <link linkend="install.configure.with-bzip2-dir">--with-bz2[=DIR]</link> lors de la compilation de PHP pour l'activer. Ce module requiert la librairie bzip2/libbzip2, version &gt;= 1.0.x. </para> <sect1 id="bzip2-example"> <title>Exemple de compression bzip2</title> <para> Cet exemple ouvre un fichier temporaire, et &eacute;crit une ligne de test, puis il en affiche le contenu. </para> <example> <title>Exemple avec bzip2</title> <programlisting role="php">&lt;?php$filename = "/tmp/fichier_de_test.bz2";$str = "Ceci est une cha&icirc;ne de test.\n";// ouvre le fichier en &eacute;criture$bz = bzopen($filename, "w");// &eacute;crit une cha&icirc;ne dans le fichierbzwrite($bz, $str);// ferme le fichierbzclose($bz);// ouvre le fichier en lecture$bz = bzopen($filename, "r");// lit 10 caract&egrave;resprint bzread($bz, 10);// affiche tout le reste du fichier, puis le fermeprint bzread($bz);bzclose($bz);?&gt; </programlisting> </example> </sect1> </partintro> <refentry id="function.bzclose"> <refnamediv> <refname>bzclose</refname> <refpurpose>Ferme un fichier bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>bzclose</function></funcdef> <paramdef>resource <parameter>bz</parameter></paramdef> </funcprototype> </funcsynopsis> <para> <function>bzclose</function> ferme le fichier bzip2 repr&eacute;sent&eacute; par le pointeur <parameter>bz</parameter>. </para> <para> <function>bzclose</function> retourne &true; en cas de succ&egrave;s, et &false; sinon. </para> <para> Le pointeur de fichier <parameter>bz</parameter> doit &ecirc;tre valide, et avoir &eacute;t&eacute; ouvert avec <function>bzopen</function>. </para> <para> Voir aussi <function>bzopen</function>. </para> </refsect1> </refentry> <refentry id="function.bzcompress"> <refnamediv> <refname>bzcompress</refname> <refpurpose>Compresse une cha&icirc;ne avec bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>string <function>bzcompress</function></funcdef> <paramdef>string <parameter>source</parameter></paramdef> <paramdef>int <parameter><optional>blocksize</optional></parameter> </paramdef> <paramdef>int <parameter><optional>workfactor</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> <function>bzcompress</function> compresse la cha&icirc;ne <parameter>source</parameter> et retourne les donn&eacute;es ainsi encod&eacute;e. </para> <para> Le param&egrave;tre optionnel <parameter>blocksize</parameter> sp&eacute;cifie la taille de bloc utilis&eacute; durant la compression, et doit &ecirc;tre un nombre de 1 &agrave; 9, sachant que 9 repr&eacute;sente la meilleure compression, mais qu'elle utilise plus de ressource pour ce faire. <parameter>blocksize</parameter> vaut par d&eacute;faut 4. </para> <para> Le param&egrave;tre optionnel <parameter>workfactor</parameter> contr&ocirc;le le comportement de la compression dans les pires cas de donn&eacute;es hautement r&eacute;p&eacute;titives. Cette valeur peut aller de 0 &agrave; 250 (0 est une valeur sp&eacute;ciale, et 30 la valeur par d&eacute;faut). En dehors de <parameter>workfactor</parameter>, le r&eacute;sultat sera le m&ecirc;me. </para> <para> <example> <title>Exemple avec <function>bzcompress</function></title> <programlisting role="php">&lt;?php$str = "donn&eacute;es de test";$bzstr = bzcompress($str, 9);?&gt; </programlisting> </example> </para> <para> Voir aussi <function>bzdecompress</function>. </para> </refsect1> </refentry> <refentry id="function.bzdecompress"> <refnamediv> <refname>bzdecompress</refname> <refpurpose>D&eacute;compresse une cha&icirc;ne bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>string <function>bzdecompress</function></funcdef> <paramdef>string <parameter>source</parameter></paramdef> <paramdef>int <parameter><optional>small</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> <function>bzdecompress</function> d&eacute;compresse la cha&icirc;ne <parameter>source</parameter>, en supposant qu'elle a &eacute;t&eacute; compress&eacute;e avec bzip2, puis la retourne. Si le param&egrave;tre optionnel <parameter>small</parameter> vaut &true;, un autre algorithme de d&eacute;compression sera utilis&eacute; : il consomme moins de m&eacute;moire (le maximum demand&eacute; tombe autour de 2300 ko), mais fonctionne globalement &agrave; la moiti&eacute; de la vitesse. Reportez-vous &agrave; la <ulink url="&url.bzip2;">documentation bzip2</ulink> pour plus de d&eacute;tails sur cette fonctionnalit&eacute;. </para> <para> <example> <title>Exemple avec <function>bzdecompress</function></title> <programlisting role="php">&lt;?php$str = $bzdecompress($bzstr);?&gt; </programlisting> </example> </para> <para> Voir aussi <function>bzcompress</function>. </para> </refsect1> </refentry> <refentry id="function.bzerrno"> <refnamediv> <refname>bzerrno</refname> <refpurpose>Retourne le num&eacute;ro d'erreur bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>bzerrno</function></funcdef> <paramdef>resource <parameter>bz</parameter></paramdef> </funcprototype> </funcsynopsis> <para> <function>bzerrno</function> retourne le num&eacute;ro d'erreur du fichier bz2 repr&eacute;sent&eacute; par le pointeur <parameter>bz</parameter>. </para> <para> Voir aussi <function>bzerror</function> et <function>bzerrstr</function>. </para> </refsect1> </refentry> <refentry id="function.bzerror"> <refnamediv> <refname>bzerror</refname> <refpurpose> Retourne le num&eacute;ro et le message d'erreur bzip2 dans un tableau </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>array <function>bzerror</function></funcdef> <paramdef>int <parameter>bz</parameter></paramdef> </funcprototype> </funcsynopsis> <para> <function>bzerror</function> retourne le num&eacute;ro et le message d'erreur du fichier bz2 repr&eacute;sent&eacute; par le pointeur <parameter>bz</parameter>. <function>bzerror</function> retourne un tableau associatif. </para> <para> <example> <title>Exemple avec <function>bzerror</function></title> <programlisting role="php">&lt;?php$error = bzerror($bz);echo $error["errno"];echo $error["errstr"];?&gt; </programlisting> </example> </para> <para> Voir aussi <function>bzerrno</function> et <function>bzerrstr</function>. </para> </refsect1> </refentry> <refentry id="function.bzerrstr"> <refnamediv> <refname>bzerrstr</refname> <refpurpose>Retourne le message d'erreur bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>string <function>bzerrstr</function></funcdef> <paramdef>resource <parameter>bz</parameter></paramdef> </funcprototype> </funcsynopsis> <para> <function>bzerrstr</function> retourne le message d'erreur du fichier bz2 repr&eacute;sent&eacute; par le pointeur <parameter>bz</parameter>. </para> <para> Voir aussi <function>bzerrno</function> et <function>bzerror</function>. </para> </refsect1> </refentry> <refentry id="function.bzflush"> <refnamediv> <refname>bzflush</refname> <refpurpose> Force l'&eacute;criture de toutes les donn&eacute;es compress&eacute;es </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>bzflush</function></funcdef> <paramdef>resource <parameter>bz</parameter></paramdef> </funcprototype> </funcsynopsis> <para> <function>bzflush</function> vide les buffers d'&eacute;criture du fichier repr&eacute;sent&eacute; par <parameter>bz</parameter>. </para> <para> <function>bzflush</function> retourne &true; en cas de succ&egrave;s, et &false; sinon. </para> <para> Voir aussi <function>bzread</function> et <function>bzwrite</function>. </para> </refsect1> </refentry> <refentry id="function.bzopen"> <refnamediv> <refname>bzopen</refname> <refpurpose>Ouvre un fichier compress&eacute; avec bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>resource <function>bzopen</function></funcdef> <paramdef>string <parameter>filename</parameter></paramdef> <paramdef>string <parameter>mode</parameter></paramdef> </funcprototype> </funcsynopsis> <para> <function>bzopen</function> ouvre un fichier bzip2 (.bz2) en &eacute;criture ou en lecture. <parameter>filename</parameter> est le nom du fichier &agrave; ouvrir. <parameter>mode</parameter> est similaire au m&ecirc;me param&egrave;tre de la fonction <function>fopen</function> (`r' pour lecture, `w' pour &eacute;criture, etc.). </para> <para> Si l'ouverture &eacute;choue, <function>bzopen</function> retourne &false;, sinon, elle retourne un pointeur de fichier. </para> <para> <example> <title>Exemple avec <function>bzopen</function></title> <programlisting role="php">&lt;?php$bz = bzopen("/tmp/foo.bz2", "r");?&gt; </programlisting> </example> </para> <para> Voir aussi <function>bzclose</function>. </para> </refsect1> </refentry> <refentry id="function.bzread"> <refnamediv> <refname>bzread</refname> <refpurpose>Lecture binaire d'un fichier bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>string <function>bzread</function></funcdef> <paramdef>resource <parameter>bz</parameter></paramdef> <paramdef>int <parameter><optional>length</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> <function>bzread</function> lit jusqu'&agrave; <parameter>length</parameter> octets depuis le fichier bzip2, r&eacute;f&eacute;renc&eacute; par le pointeur <parameter>bz</parameter>. La lecture s'arr&ecirc;te lorsque <parameter>length</parameter> octets (non compress&eacute;s) ont &eacute;t&eacute; lus, qu'une erreur est rencontr&eacute;e, ou bien que la fin du fichier a &eacute;t&eacute; atteinte : le premier des trois qui survient. Si le param&egrave;tre optionnel <parameter>length</parameter> est omis, <function>bzread</function> lit 1024 octets (non compress&eacute;s) en m&ecirc;me temps. </para> <para> <example> <title>Exemple avec <function>bzread</function></title> <programlisting role="php">&lt;?php$bz = bzopen("/tmp/foo.bz2", "r");$str = bzread($bz, 2048);echo $str;?&gt; </programlisting> </example> </para> <para> Voir aussi <function>bzwrite</function> et <function>bzopen</function>. </para> </refsect1> </refentry> <refentry id="function.bzwrite"> <refnamediv> <refname>bzwrite</refname> <refpurpose>Ecriture binaire dans un fichier bzip2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>bzwrite</function></funcdef> <paramdef>resource <parameter>bz</parameter></paramdef> <paramdef>string <parameter>data</parameter></paramdef> <paramdef>int <parameter><optional>length</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> <function>bzwrite</function> &eacute;crit le contenu de la cha&icirc;ne <parameter>data</parameter> dans le fichier bzip2 repr&eacute;sent&eacute; par <parameter>bz</parameter>. Si le param&egrave;tre optionnel <parameter>length</parameter> est fourni, l'&eacute;criture sera arr&ecirc;t&eacute;e apr&egrave;s l'&eacute;criture de <parameter>length</parameter> octets (non compress&eacute;s), ou la fin de la cha&icirc;ne (le premier qui survient). </para> <para> <example> <title>Exemple <function>bzwrite</function></title> <programlisting role="php">&lt;?php$str = "donn&eacute;es non compress&eacute;es";$bz = bzopen("/tmp/foo.bz2", "w");bzwrite($bz, $str, strlen($str));?&gt; </programlisting> </example> </para> <para> Voir aussi <function>bzread</function> et <function>bzopen</function>. </para> </refsect1> </refentry> </reference><!-- Keep this comment at the end of the fileLocal variables:mode: sgmlsgml-omittag:tsgml-shorttag:tsgml-minimize-attributes:nilsgml-always-quote-attributes:tsgml-indent-step:1sgml-indent-data:tsgml-parent-document:nilsgml-default-dtd-file:"../../manual.ced"sgml-exposed-tags:nilsgml-local-catalogs:nilsgml-local-ecat-files:nilEnd:--> \ No newline at end of file + <reference id="ref.bzip2"> + <title>Compression Bzip2</title> + <titleabbrev>Bzip2</titleabbrev> + <partintro> + <para> + Ce module utilise les fonctions de la librairie + <ulink url="&url.bzip2;">bzip2</ulink>, de Julian Seward pour + &eacute;crire et lire des fichier bzip2 (.bz2) de mani&egrave;re transparente. + </para> + <para> + Le support <acronym>bzip2</acronym> par PHP n'est pas activ&eacute; par + d&eacute;faut. Vous devez utiliser l'option de configuration + <link linkend="install.configure.with-bzip2-dir">--with-bz2[=DIR]</link> + lors de la compilation de PHP pour l'activer. Ce module requiert la librairie + bzip2/libbzip2, version &gt;= 1.0.x. + </para> + <sect1 id="bzip2-example"> + <title>Exemple de compression bzip2</title> + <para> + Cet exemple ouvre un fichier temporaire, et &eacute;crit une ligne de test, + puis il en affiche le contenu. + </para> + <example> + <title>Exemple avec bzip2</title> + <programlisting role="php"> +&lt;?php + +$filename = "/tmp/fichier_de_test.bz2"; +$str = "Ceci est une cha&icirc;ne de test.\n"; + +// ouvre le fichier en &eacute;criture +$bz = bzopen($filename, "w"); + +// &eacute;crit une cha&icirc;ne dans le fichier +bzwrite($bz, $str); + +// ferme le fichier +bzclose($bz); + +// ouvre le fichier en lecture +$bz = bzopen($filename, "r"); + +// lit 10 caract&egrave;res +print bzread($bz, 10); + +// affiche tout le reste du fichier, puis le ferme +print bzread($bz); + +bzclose($bz); + +?&gt; + </programlisting> + </example> + </sect1> + </partintro> + <refentry id="function.bzclose"> + <refnamediv> + <refname>bzclose</refname> + <refpurpose>Ferme un fichier bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>bzclose</function></funcdef> + <paramdef>resource <parameter>bz</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzclose</function> ferme le fichier bzip2 + repr&eacute;sent&eacute; par le pointeur <parameter>bz</parameter>. + </para> + <para> + <function>bzclose</function> retourne &true; + en cas de succ&egrave;s, et &false; sinon. + </para> + <para> + Le pointeur de fichier <parameter>bz</parameter> doit &ecirc;tre + valide, et avoir &eacute;t&eacute; ouvert avec <function>bzopen</function>. + </para> + <para> + Voir aussi <function>bzopen</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzcompress"> + <refnamediv> + <refname>bzcompress</refname> + <refpurpose>Compresse une cha&icirc;ne avec bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>bzcompress</function></funcdef> + <paramdef>string <parameter>source</parameter></paramdef> + <paramdef>int + <parameter><optional>blocksize</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>workfactor</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzcompress</function> compresse la cha&icirc;ne + <parameter>source</parameter> et retourne les donn&eacute;es + ainsi encod&eacute;e. + </para> + <para> + Le param&egrave;tre optionnel <parameter>blocksize</parameter> sp&eacute;cifie + la taille de bloc utilis&eacute; durant la compression, et doit &ecirc;tre un + nombre de 1 &agrave; 9, sachant que 9 repr&eacute;sente la meilleure compression, + mais qu'elle utilise plus de ressource pour ce faire. + <parameter>blocksize</parameter> vaut par d&eacute;faut 4. + </para> + <para> + Le param&egrave;tre optionnel <parameter>workfactor</parameter> contr&ocirc;le + le comportement de la compression dans les pires cas de donn&eacute;es + hautement r&eacute;p&eacute;titives. Cette valeur peut aller de 0 &agrave; 250 (0 + est une valeur sp&eacute;ciale, et 30 la valeur par d&eacute;faut). En dehors + de <parameter>workfactor</parameter>, le r&eacute;sultat sera le m&ecirc;me. + </para> + <para> + <example> + <title>Exemple avec <function>bzcompress</function></title> + <programlisting role="php"> +&lt;?php +$str = "donn&eacute;es de test"; +$bzstr = bzcompress($str, 9); +?&gt; + </programlisting> + </example> + </para> + <para> + Voir aussi <function>bzdecompress</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzdecompress"> + <refnamediv> + <refname>bzdecompress</refname> + <refpurpose>D&eacute;compresse une cha&icirc;ne bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>bzdecompress</function></funcdef> + <paramdef>string <parameter>source</parameter></paramdef> + <paramdef>int + <parameter><optional>small</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzdecompress</function> d&eacute;compresse la cha&icirc;ne + <parameter>source</parameter>, en supposant qu'elle a &eacute;t&eacute; + compress&eacute;e avec bzip2, puis la retourne. Si le param&egrave;tre + optionnel <parameter>small</parameter> vaut &true;, + un autre algorithme de d&eacute;compression sera utilis&eacute; : il consomme + moins de m&eacute;moire (le maximum demand&eacute; tombe autour de + 2300 ko), mais fonctionne globalement &agrave; la moiti&eacute; de + la vitesse. Reportez-vous &agrave; la + <ulink url="&url.bzip2;">documentation bzip2</ulink> pour plus de + d&eacute;tails sur cette fonctionnalit&eacute;. + </para> + <para> + <example> + <title>Exemple avec <function>bzdecompress</function></title> + <programlisting role="php"> +&lt;?php +$str = $bzdecompress($bzstr); +?&gt; + </programlisting> + </example> + </para> + <para> + Voir aussi <function>bzcompress</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzerrno"> + <refnamediv> + <refname>bzerrno</refname> + <refpurpose>Retourne le num&eacute;ro d'erreur bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>bzerrno</function></funcdef> + <paramdef>resource <parameter>bz</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzerrno</function> retourne le num&eacute;ro d'erreur + du fichier bz2 repr&eacute;sent&eacute; par le pointeur + <parameter>bz</parameter>. + </para> + <para> + Voir aussi <function>bzerror</function> et <function>bzerrstr</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzerror"> + <refnamediv> + <refname>bzerror</refname> + <refpurpose> + Retourne le num&eacute;ro et le message d'erreur bzip2 dans un tableau + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>bzerror</function></funcdef> + <paramdef>int <parameter>bz</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzerror</function> retourne le num&eacute;ro et le message d'erreur + du fichier bz2 repr&eacute;sent&eacute; par le pointeur + <parameter>bz</parameter>. <function>bzerror</function> retourne + un tableau associatif. + </para> + <para> + <example> + <title>Exemple avec <function>bzerror</function></title> + <programlisting role="php"> +&lt;?php +$error = bzerror($bz); + +echo $error["errno"]; +echo $error["errstr"]; +?&gt; + </programlisting> + </example> + </para> + <para> + Voir aussi <function>bzerrno</function> et <function>bzerrstr</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzerrstr"> + <refnamediv> + <refname>bzerrstr</refname> + <refpurpose>Retourne le message d'erreur bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>bzerrstr</function></funcdef> + <paramdef>resource <parameter>bz</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzerrstr</function> retourne le message d'erreur + du fichier bz2 repr&eacute;sent&eacute; par le pointeur + <parameter>bz</parameter>. + </para> + <para> + Voir aussi <function>bzerrno</function> et <function>bzerror</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzflush"> + <refnamediv> + <refname>bzflush</refname> + <refpurpose> + Force l'&eacute;criture de toutes les donn&eacute;es compress&eacute;es + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>bzflush</function></funcdef> + <paramdef>resource <parameter>bz</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzflush</function> vide les buffers d'&eacute;criture du + fichier repr&eacute;sent&eacute; par <parameter>bz</parameter>. + </para> + <para> + <function>bzflush</function> retourne &true; + en cas de succ&egrave;s, et &false; sinon. + </para> + <para> + Voir aussi <function>bzread</function> et <function>bzwrite</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzopen"> + <refnamediv> + <refname>bzopen</refname> + <refpurpose>Ouvre un fichier compress&eacute; avec bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>bzopen</function></funcdef> + <paramdef>string <parameter>filename</parameter></paramdef> + <paramdef>string <parameter>mode</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzopen</function> ouvre un fichier bzip2 (.bz2) + en &eacute;criture ou en lecture. <parameter>filename</parameter> + est le nom du fichier &agrave; ouvrir. <parameter>mode</parameter> + est similaire au m&ecirc;me param&egrave;tre de la fonction <function>fopen</function> + (`r' pour lecture, `w' pour &eacute;criture, etc.). + </para> + <para> + Si l'ouverture &eacute;choue, <function>bzopen</function> retourne + &false;, sinon, elle retourne un pointeur + de fichier. + </para> + <para> + <example> + <title>Exemple avec <function>bzopen</function></title> + <programlisting role="php"> +&lt;?php +$bz = bzopen("/tmp/foo.bz2", "r"); +?&gt; + </programlisting> + </example> + </para> + <para> + Voir aussi <function>bzclose</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzread"> + <refnamediv> + <refname>bzread</refname> + <refpurpose>Lecture binaire d'un fichier bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>bzread</function></funcdef> + <paramdef>resource <parameter>bz</parameter></paramdef> + <paramdef>int + <parameter><optional>length</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzread</function> lit jusqu'&agrave; <parameter>length</parameter> + octets depuis le fichier bzip2, r&eacute;f&eacute;renc&eacute; par le pointeur + <parameter>bz</parameter>. La lecture s'arr&ecirc;te lorsque + <parameter>length</parameter> octets (non compress&eacute;s) + ont &eacute;t&eacute; lus, qu'une erreur est rencontr&eacute;e, + ou bien que la fin du fichier a &eacute;t&eacute; atteinte : + le premier des trois qui survient. Si le param&egrave;tre + optionnel <parameter>length</parameter> est omis, + <function>bzread</function> lit 1024 octets (non compress&eacute;s) en + m&ecirc;me temps. + </para> + <para> + <example> + <title>Exemple avec <function>bzread</function></title> + <programlisting role="php"> +&lt;?php +$bz = bzopen("/tmp/foo.bz2", "r"); +$str = bzread($bz, 2048); +echo $str; +?&gt; + </programlisting> + </example> + </para> + <para> + Voir aussi <function>bzwrite</function> et <function>bzopen</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.bzwrite"> + <refnamediv> + <refname>bzwrite</refname> + <refpurpose>Ecriture binaire dans un fichier bzip2</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>bzwrite</function></funcdef> + <paramdef>resource <parameter>bz</parameter></paramdef> + <paramdef>string <parameter>data</parameter></paramdef> + <paramdef>int + <parameter><optional>length</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>bzwrite</function> &eacute;crit le contenu de la cha&icirc;ne + <parameter>data</parameter> dans le fichier bzip2 repr&eacute;sent&eacute; + par <parameter>bz</parameter>. Si le param&egrave;tre optionnel + <parameter>length</parameter> est fourni, l'&eacute;criture sera + arr&ecirc;t&eacute;e apr&egrave;s l'&eacute;criture de + <parameter>length</parameter> octets (non compress&eacute;s), + ou la fin de la cha&icirc;ne (le premier qui survient). + </para> + <para> + <example> + <title>Exemple <function>bzwrite</function></title> + <programlisting role="php"> +&lt;?php +$str = "donn&eacute;es non compress&eacute;es"; +$bz = bzopen("/tmp/foo.bz2", "w"); +bzwrite($bz, $str, strlen($str)); +?&gt; + </programlisting> + </example> + </para> + <para> + Voir aussi <function>bzread</function> et <function>bzopen</function>. + </para> + </refsect1> + </refentry> + </reference> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/it/features/error-handling.xml diff -u phpdoc/it/features/error-handling.xml:1.3 phpdoc/it/features/error-handling.xml:1.4 --- phpdoc/it/features/error-handling.xml:1.3 Sun Jul 30 20:38:22 2000 +++ phpdoc/it/features/error-handling.xml Sat Jul 7 19:11:31 2001 @@ -1,154 +1,154 @@ -<chapter id="features.error-handling"> - <title>Gestione degli errori</title> - - <para> - In PHP sono presenti diversi tipi di errori e avvertimenti (warning): - - <table> - <title>PHP - Tipi di errore</title> - <tgroup cols="4"> - <thead> - <row> - <entry>valore</entry> - <entry>simbolo</entry> - <entry>descrizione</entry> - <entry>note</entry> - </row> - </thead> - <tbody> - <row> - <entry>1</entry> - <entry>E_ERROR</entry> - <entry>Errore run-time fatale</entry> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>E_WARNING</entry> - <entry>Warning run-time(errore non fatale)</entry> - <entry></entry> - </row> - <row> - <entry>4</entry> - <entry>E_PARSE</entry> - <entry>Errore nel parsing in compilazione</entry> - <entry></entry> - </row> - <row> - <entry>8</entry> - <entry>E_NOTICE </entry> - <entry> - Notifiche run-time(meno seri dei warning) - </entry> - <entry></entry> - </row> - <row> - <entry>16</entry> - <entry>E_CORE_ERROR</entry> - <entry>Errore fatale nella fase di startup inizale di PHP</entry> - <entry>Solo PHP 4</entry> - </row> - <row> - <entry>32</entry> - <entry>E_CORE_WARNING</entry> - <entry>Warning (errore non fatale) nella fase di startup inizale di PHP</entry> - <entry>Solo PHP 4</entry> - </row> - <row> - <entry>64</entry> - <entry>E_COMPILE_ERROR</entry> - <entry>Errore fatale in fase di compilazione</entry> - <entry>Solo PHP 4</entry> - </row> - <row> - <entry>128</entry> - <entry>E_COMPILE_WARNING</entry> - <entry>Warning (errore non fatale) in fase di compilazione</entry> - <entry>Solo PHP 4</entry> - </row> - <row> - <entry>256</entry> - <entry>E_USER_ERROR</entry> - <entry>Messagio di errore generato dall'utente</entry> - <entry>Solo PHP 4</entry> - </row> - <row> - <entry>512</entry> - <entry>E_USER_WARNING</entry> - <entry>Messaggio di avvertimento (warning) generato dall'utente</entry> - <entry>Solo PHP 4</entry> - </row> - <row> - <entry>1024</entry> - <entry>E_USER_NOTICE </entry> - <entry>Messagio di notifica generato dall'utente</entry> - <entry>Solo PHP 4</entry> - </row> - <row> - <entry></entry> - <entry>E_ALL</entry> - <entry>Tutti i precedenti</entry> - <entry>Solo PHP 4</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - I valori presenti nella tabella (sia numerici che simbolici) sono utilizzati - per creare delle bitmask per specificare quali errori da cercare. Si possono - usare gli operatori sui bit '|','&amp;' e '~' per combinare questi valori e - mascherare certi tipi di errori. Le configurazioni predefinite per effettuare - il report di tutti gli errori eccetto le notifiche sono <literal>E_ALL & ~E_NOTICE</literal> - per PHP4 e 7 per PHP3 (PHP3 non supporta le costanti simboliche). - </para> - <para> - Le configurazioni possono essere cambiate nel file ini con la direttiva - error_reporting. Si pu&ograve; anche utilizzare il file di configurazione di - Apache httpd.conf con la direttiva php_error_reporting (php3_error_reporting - per PHP 3) oppure ancora in fase di esecuzione di uno script con la - funzione <function>error_reporting</function>. - </para> - <warning> - <para> - Quando si esegue un'upgrade del codice o dei server da PHP3 a PHP4 &egrave; - necessario controllare questi settaggi e le chiamate a <function>error_reporting</function> - oppure potrebbe disabilitarsi il report dei nuovi tipi di errore, specialmente - E_COMPILE_ERROR. Questo potrebbe portare a documenti vuoti senza alcun - feedback sulle cause o dove guardare per trovare il problema. - </para> - </warning> - - <para> - Tutte le <link linkend="language.expressions">espressioni PHP</link> possono anche - venir chiamate con il prefisso "@", che disabilita il report degli errori per quella - particolare espressione. Se capita un errore in una di queste espressioni e l'opzione - <link linkend="ini.track-errors">track_errors</link> è attivata, si pu&ograve; trovare - il messaggio d'errore nella variabile globale $php_errormsg. - </para> - - <warning> - <para> - Attualmente il prefisso "@" disabilita il report anche per gli errori - critici che terminano l'esecuzione dello script. - </para> - </warning> - - </chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> +<chapter id="features.error-handling"> + <title>Gestione degli errori</title> + + <para> + In PHP sono presenti diversi tipi di errori e avvertimenti (warning): + + <table> + <title>PHP - Tipi di errore</title> + <tgroup cols="4"> + <thead> + <row> + <entry>valore</entry> + <entry>simbolo</entry> + <entry>descrizione</entry> + <entry>note</entry> + </row> + </thead> + <tbody> + <row> + <entry>1</entry> + <entry>E_ERROR</entry> + <entry>Errore run-time fatale</entry> + <entry></entry> + </row> + <row> + <entry>2</entry> + <entry>E_WARNING</entry> + <entry>Warning run-time(errore non fatale)</entry> + <entry></entry> + </row> + <row> + <entry>4</entry> + <entry>E_PARSE</entry> + <entry>Errore nel parsing in compilazione</entry> + <entry></entry> + </row> + <row> + <entry>8</entry> + <entry>E_NOTICE </entry> + <entry> + Notifiche run-time(meno seri dei warning) + </entry> + <entry></entry> + </row> + <row> + <entry>16</entry> + <entry>E_CORE_ERROR</entry> + <entry>Errore fatale nella fase di startup inizale di PHP</entry> + <entry>Solo PHP 4</entry> + </row> + <row> + <entry>32</entry> + <entry>E_CORE_WARNING</entry> + <entry>Warning (errore non fatale) nella fase di startup inizale di PHP</entry> + <entry>Solo PHP 4</entry> + </row> + <row> + <entry>64</entry> + <entry>E_COMPILE_ERROR</entry> + <entry>Errore fatale in fase di compilazione</entry> + <entry>Solo PHP 4</entry> + </row> + <row> + <entry>128</entry> + <entry>E_COMPILE_WARNING</entry> + <entry>Warning (errore non fatale) in fase di compilazione</entry> + <entry>Solo PHP 4</entry> + </row> + <row> + <entry>256</entry> + <entry>E_USER_ERROR</entry> + <entry>Messagio di errore generato dall'utente</entry> + <entry>Solo PHP 4</entry> + </row> + <row> + <entry>512</entry> + <entry>E_USER_WARNING</entry> + <entry>Messaggio di avvertimento (warning) generato dall'utente</entry> + <entry>Solo PHP 4</entry> + </row> + <row> + <entry>1024</entry> + <entry>E_USER_NOTICE </entry> + <entry>Messagio di notifica generato dall'utente</entry> + <entry>Solo PHP 4</entry> + </row> + <row> + <entry></entry> + <entry>E_ALL</entry> + <entry>Tutti i precedenti</entry> + <entry>Solo PHP 4</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + I valori presenti nella tabella (sia numerici che simbolici) sono utilizzati + per creare delle bitmask per specificare quali errori da cercare. Si possono + usare gli operatori sui bit '|','&amp;' e '~' per combinare questi valori e + mascherare certi tipi di errori. Le configurazioni predefinite per effettuare + il report di tutti gli errori eccetto le notifiche sono <literal>E_ALL & ~E_NOTICE</literal> + per PHP4 e 7 per PHP3 (PHP3 non supporta le costanti simboliche). + </para> + <para> + Le configurazioni possono essere cambiate nel file ini con la direttiva + error_reporting. Si pu&ograve; anche utilizzare il file di configurazione di + Apache httpd.conf con la direttiva php_error_reporting (php3_error_reporting + per PHP 3) oppure ancora in fase di esecuzione di uno script con la + funzione <function>error_reporting</function>. + </para> + <warning> + <para> + Quando si esegue un'upgrade del codice o dei server da PHP3 a PHP4 &egrave; + necessario controllare questi settaggi e le chiamate a <function>error_reporting</function> + oppure potrebbe disabilitarsi il report dei nuovi tipi di errore, specialmente + E_COMPILE_ERROR. Questo potrebbe portare a documenti vuoti senza alcun + feedback sulle cause o dove guardare per trovare il problema. + </para> + </warning> + + <para> + Tutte le <link linkend="language.expressions">espressioni PHP</link> possono anche + venir chiamate con il prefisso "@", che disabilita il report degli errori per quella + particolare espressione. Se capita un errore in una di queste espressioni e l'opzione + <link linkend="ini.track-errors">track_errors</link> è attivata, si pu&ograve; trovare + il messaggio d'errore nella variabile globale $php_errormsg. + </para> + + <warning> + <para> + Attualmente il prefisso "@" disabilita il report anche per gli errori + critici che terminano l'esecuzione dello script. + </para> + </warning> + + </chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/it/features/remote-files.xml diff -u phpdoc/it/features/remote-files.xml:1.3 phpdoc/it/features/remote-files.xml:1.4 --- phpdoc/it/features/remote-files.xml:1.3 Sun Jul 30 20:44:09 2000 +++ phpdoc/it/features/remote-files.xml Sat Jul 7 19:11:32 2001 @@ -1,104 +1,104 @@ - <chapter id="features.remote-files"> - <title>Utilizzo di file remoti</title> - - <para> - Quando viene abilitato il supporto per l "URL fopen wrapper" durante - la configurazione di PHP (avviene automaticamente a meno che si - specifichi espressamente il flag<option>--disable-url-fopen-wrapper</option>), - si possono usare URL FTP e HTTP con la maggior parte delle funzioni che - richiedono nomi di file come parametri, incluse le funzioni <function>require</function> - e <function>include</function>. - - <note> - <para> - Non si possono usare i file remoti con <function>include</function> e - <function>require</function> sotto Windows. - </para> - </note> - </para> - - <para> - Per esempio, si pu&ograve; usare per aprire un file da un web server remoto, - elaborare i dati presi da remoto, e usarli per effetuare delle query, - o semplicemente visualizzarli con lo stile del proprio sito web. - </para> - - <para> - <example> - <title>Legere il titolo di una pagina web remota</title> - <programlisting> -&lt;?php - $file = fopen("http://www.php.net/", "r"); - if (!$file) { - echo "&lt;p>Errore nell'apertura del file remoto.\n"; - exit; - } - while (!feof($file)) { - $line = fgets($file, 1024); - /* Funziona solo se i tag del titolo sono sulla stessa linea. */ - if (eregi("&lt;title>(.*)&lt;/title>", $line, $out)) { - $title = $out[1]; - break; - } - } - fclose($file); -?&gt; - </programlisting> - </example> - </para> - - <para> - Si pu&ograve; anche scrivere in un file remoto via FTP se l'utente con cui ci - si connette ha le autorizzazioni necessarie, e il file non &egrave; gi&agrave; presente. - Per connettersi con un utenti specifico si ha bisogno di specificare lo username - (e la relativa password) dentro l'URL in questo modo: - 'ftp://user:password@ftp.test.com/dir/del/file'. (Si pu&ograve; usare lo stesso - tipo di sintassi per accedere a file via HTTP quando richiedono autenticazione). - </para> - - <para> - <example> - <title>Salvataggio di dati su server remoto</title> - <programlisting> -&lt;?php - $file = fopen("ftp://ftp.php.net/incoming/outputfile", "w"); - if (!$file) { - echo "&lt;p>Errore nell'apertura del file remoto in scrittura.\n"; - exit; - } - /* Scrittura del file. */ - fputs($file, "$HTTP_USER_AGENT\n"); - fclose($file); -?&gt; - </programlisting> - </example> - - <note> - <para> - Dall'esempio precedente ci si pu&ograve; fare un'idea di come usare questa - tecnica per effettuare dei log in remoto, ma come gi&agrave; accennato non &egrave; - possibile scrivere su file gi&agrave; esistenti con questo sitema. - Per fare una procedura di log distribuito &egrave; più indicata la funzione - <function>syslog</function>. - </para> - </note> - </para> - - </chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> + <chapter id="features.remote-files"> + <title>Utilizzo di file remoti</title> + + <para> + Quando viene abilitato il supporto per l "URL fopen wrapper" durante + la configurazione di PHP (avviene automaticamente a meno che si + specifichi espressamente il flag<option>--disable-url-fopen-wrapper</option>), + si possono usare URL FTP e HTTP con la maggior parte delle funzioni che + richiedono nomi di file come parametri, incluse le funzioni <function>require</function> + e <function>include</function>. + + <note> + <para> + Non si possono usare i file remoti con <function>include</function> e + <function>require</function> sotto Windows. + </para> + </note> + </para> + + <para> + Per esempio, si pu&ograve; usare per aprire un file da un web server remoto, + elaborare i dati presi da remoto, e usarli per effetuare delle query, + o semplicemente visualizzarli con lo stile del proprio sito web. + </para> + + <para> + <example> + <title>Legere il titolo di una pagina web remota</title> + <programlisting> +&lt;?php + $file = fopen("http://www.php.net/", "r"); + if (!$file) { + echo "&lt;p>Errore nell'apertura del file remoto.\n"; + exit; + } + while (!feof($file)) { + $line = fgets($file, 1024); + /* Funziona solo se i tag del titolo sono sulla stessa linea. */ + if (eregi("&lt;title>(.*)&lt;/title>", $line, $out)) { + $title = $out[1]; + break; + } + } + fclose($file); +?&gt; + </programlisting> + </example> + </para> + + <para> + Si pu&ograve; anche scrivere in un file remoto via FTP se l'utente con cui ci + si connette ha le autorizzazioni necessarie, e il file non &egrave; gi&agrave; presente. + Per connettersi con un utenti specifico si ha bisogno di specificare lo username + (e la relativa password) dentro l'URL in questo modo: + 'ftp://user:password@ftp.test.com/dir/del/file'. (Si pu&ograve; usare lo stesso + tipo di sintassi per accedere a file via HTTP quando richiedono autenticazione). + </para> + + <para> + <example> + <title>Salvataggio di dati su server remoto</title> + <programlisting> +&lt;?php + $file = fopen("ftp://ftp.php.net/incoming/outputfile", "w"); + if (!$file) { + echo "&lt;p>Errore nell'apertura del file remoto in scrittura.\n"; + exit; + } + /* Scrittura del file. */ + fputs($file, "$HTTP_USER_AGENT\n"); + fclose($file); +?&gt; + </programlisting> + </example> + + <note> + <para> + Dall'esempio precedente ci si pu&ograve; fare un'idea di come usare questa + tecnica per effettuare dei log in remoto, ma come gi&agrave; accennato non &egrave; + possibile scrivere su file gi&agrave; esistenti con questo sitema. + Per fare una procedura di log distribuito &egrave; più indicata la funzione + <function>syslog</function>. + </para> + </note> + </para> + + </chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/it/functions/mssql.xml diff -u phpdoc/it/functions/mssql.xml:1.6 phpdoc/it/functions/mssql.xml:1.7 --- phpdoc/it/functions/mssql.xml:1.6 Sat Jun 23 16:35:12 2001 +++ phpdoc/it/functions/mssql.xml Sat Jul 7 19:11:33 2001 @@ -1,694 +1,694 @@ - <reference id="ref.mssql"> - <title>Funzioni per Microsoft SQL Server</title> - <titleabbrev>MS SQL Server</titleabbrev> - - <refentry id="function.mssql-close"> - <refnamediv> - <refname>mssql_close</refname> - <refpurpose>Chiude la connessione con MS SQL Server</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_close</function></funcdef> - <paramdef>int - <parameter><optional>id_connessione</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce: vero se l'operazione riesce, falso se si verifica un errore. - </para> - <para> - La funzione <function>mssql_close</function> chiude la connessione - ad un database MS SQL - Server che è associata all' argomento id_connessione. - Se l' id_connessione non viene indicato, si fa riferimento all'ultima connessione - aperta. - </para> - <para> - Nota: solitamente non è necessario l'uso della funzione, dato che - tutte le connessioni non-persistenti sono chiuse automaticamente al - termine dell'esecuzione dello script. - </para> - <para> - <function>mssql_close</function> non chiude i collegamenti persistenti - aperti utilizzando <function>mssql_pconnect</function>. - </para> - <para> - Vedere anche: <function>mssql_connect</function>, - <function>mssql_pconnect</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-connect"> - <refnamediv> - <refname>mssql_connect</refname> - <refpurpose>Apre una connessione con un server MS SQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_connect</function></funcdef> - <paramdef>string - <parameter><optional>nome_server</optional></parameter> - </paramdef> - <paramdef>string - <parameter><optional>nome_utente</optional></parameter> - </paramdef> - <paramdef>string - <parameter><optional>password</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce: un identificativo di connessione su l'operazione riesce, - oppure falso se si verifica un errore. - </para> - <para> - La funzione <function>mssql_connect</function> realizza una connessione - con un server MS SQL. L' argomento nome_server deve essere un nome valido - di server come definito nel file 'interfaces'. - </para> - <para> - Qualora la funzione <function>mssql_connect</function> venga eseguita - una seconda volta con i medesimi parametri, non viene realizzata una nuova - connessione, ma, invece, viene restituito l'identificativo della connessione - già aperta. - </para> - <para> - La connessione con il server verrà chiusa non appena lo script terminerà - l'esecuzione, a meno che la connessione non sia già stata chiusa utilizzando - la funzione <function>mssql_close</function>. - </para> - <para> - Vedere anche <function>mssql_pconnect</function>, e - <function>mssql_close</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-data-seek"> - <refnamediv> - <refname>mssql_data_seek</refname> - <refpurpose>Sposta il puntatore di riga interno</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_data_seek</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>numero_riga</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce: vero se l'operazione riesce, falso se si verifica un errore. - </para> - <para> - La funzione <function>mssql_data_seek</function> sposta il puntatore - di riga, interno al risultato associato all'identificativo di risultato, - alla riga indicata dall'argomento numero_riga. La chiamata successiva a - <function>mssql_fetch_row</function> restituirà la riga richiesta. - </para> - <para> - Vedere anche <function>mssql_data_seek</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-fetch-array"> - <refnamediv> - <refname>mssql_fetch_array</refname> - <refpurpose>Restituisce una riga in un array</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_fetch_array</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce: un array corrispondente alla riga estratta, oppure - falso se non vi sono più righe. - </para> - <para> - La funzione <function>mssql_fetch_array</function> è un' estensione - della funzione - <function>mssql_fetch_row</function>. Oltre a memorizzare i dati in un array - con indice numerico, la funzione memorizza i dati in un array associativo - in cui la chiave è costituita dal nome del campo. - </para> - <para> - Un aspetto da notare è che la funzione - <function>mssql_fetch_array</function> NON è significativamente più - lenta rispetto a <function>mssql_fetch_row</function>, mentre nel contempo - fornisce funzionalità maggiori. - </para> - <para> - Per ulteriori dettagli vedere anche - <function>mssql_fetch_row</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-fetch-field"> - <refnamediv> - <refname>mssql_fetch_field</refname> - <refpurpose>Restituisce le informazioni di un campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>object <function>mssql_fetch_field</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int - <parameter><optional>offset_campo</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce un oggetto contenente le informazioni sul campo. - </para> - <para> - La funzione <function>mssql_fetch_field</function> può essere utilizzata - per ottenere informazioni sui campi presenti nel risultato di una certa query. - Se non viene specificato l'argomento offset_campo, la funzione restituisce - il campo successivo che non è ancora stato restituito da - <function>mssql_fetch_field</function>. - </para> - <para> - Le proprietà dell'oggetto sono: - </para> - <itemizedlist> - <listitem> - <simpara> - name - nome della colonna. Se la colonna è il risultato di una funzione, questa - proprietà è valorizzata con "computed#N", dove #N è un numero progressivo. - </simpara> - </listitem> - <listitem> - <simpara> - column_source - tabella da cui sono ricavate le colonne - </simpara> - </listitem> - <listitem> - <simpara> - max_length - lunghezza massima della colonna - </simpara> - </listitem> - <listitem> - <simpara> - numeric - 1 se la colonna è numerica - </simpara></listitem> - </itemizedlist> - <para> - Vedere anche <function>mssql_field_seek</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-fetch-object"> - <refnamediv> - <refname>mssql_fetch_object</refname> - <refpurpose>Restituisce una riga come oggetto</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_fetch_object</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce un oggetto le cui proprietà corrispondono alla riga estratta, - oppure falso se non vi sono più righe. - </para> - <para> - La funzione <function>mssql_fetch_object</function> è simile a - <function>mssql_fetch_array</function>, tranne che per una - differenza, la prima restituisce un oggetto, la seconda un array. - Indirettamente questo significa che si può accedere ai dati solo - attraverso il nome dei campi e non tramite il loro offset ( i numeri non - sono dei validi nomi di proprietà ). - </para> - <para> - A livello di velocità il comportamento è simile a - <function>mssql_fetch_array</function>, e quasi veloce come - <function>mssql_fetch_row</function> (la differenza è - insignificante ). - </para> - <para> - Vedere anche <function>mssql_fetch-array</function> and - <function>mssql_fetch-row</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-fetch-row"> - <refnamediv> - <refname>mssql_fetch_row</refname> - <refpurpose>Restituisce una riga come array numerato</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>mssql_fetch_row</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce un array che corrisponde alla riga estratta, - oppure falso se non vi sono più righe. - </para> - <para> - La funzione <function>mssql_fetch_row</function> estrae una riga - di dati dal risultato associato all'identificativo di risultato passato. - La riga viene restituita in un array. Ciascuna colonna è memorizzata - in un campo dell'array. Il primo ha indice 0. - </para> - <para> - Esecuzione successive di <function>mssql_fetch_rows</function> restituiscono - le righe successive presenti nel risultato, oppure falso - se non vi sono più righe. - </para> - <para> - Vedere anche <function>mssql_fetch_array</function>, - <function>mssql_fetch_object</function>, - <function>mssql_data_seek</function>, - <function>mssql_fetch_lengths</function>, e - <function>mssql_result</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-field-length"> - <refnamediv> - <refname>mssql_field_length</refname> - <refpurpose>Restituisce la lunghezza di un campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_field_length</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int - <parameter><optional>offset</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - </refsect1> - </refentry> - - <refentry id="function.mssql-field-name"> - <refnamediv> - <refname>mssql_field_name</refname> - <refpurpose>Restituisce il nome di un campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_field_name</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int - <parameter><optional>offset</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - </refsect1> - </refentry> - - <refentry id="function.mssql-field-seek"> - <refnamediv> - <refname>mssql_field_seek</refname> - <refpurpose>Posizionamento sul campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_field_seek</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>offset_campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Si posiziona sul campo richiesto. Eseguendo successivamente la - funzione <function>mssql_fetch_field</function> senza indicare alcun campo, - quest'ultima restituirà il campo richiesto tramite - <function>mssql_fetch_field</function>.</para> - <para></para> - <para> - Vedere anche <function>mssql_fetch_field</function>.</para> - </refsect1> - </refentry> - - <refentry id="function.mssql-field-type"> - <refnamediv> - <refname>mssql_field_type</refname> - <refpurpose>Restituisce il tipo di un campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>mssql_field_type</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int - <parameter><optional>offset</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - </refsect1> - </refentry> - - <refentry id="function.mssql-free-result"> - <refnamediv> - <refname>mssql_free_result</refname> - <refpurpose>Libera la memoria di un risultato</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_free_result</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione <function>mssql_free_result</function> permette - di non utilizzare molta memoria durante l'esecuzione di uno script. - Infatti, se si è sicuri di non avere più bisogno dei dati del risultato, - si può eseguire <function>mssql_free_result</function>, e la memoria associata - a <parameter>id_risultato</parameter> sarà liberata. Se la funzione - non viene utilizzata, le aree di memoria resteranno disponibili per tutta - la durata dello script. Al termine verranno liberate in modo automatico. - Tuttavia utilizzando la funzione <function>mssql_free_result</function>, - l'area di memoria del risultato associato a id_risultato, sarà liberata. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-get-last-message"> - <refnamediv> - <refname>mssql_get_last_message</refname> - <refpurpose> - Restituisce l'ultimo messaggio dal server ( oltre min_message_severity?) - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string - <function>mssql_get_last_message</function> - </funcdef> - <paramdef>void <parameter></parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsect1> - </refentry> - - <refentry id="function.mssql-min-error-severity"> - <refnamediv> - <refname>mssql_min_error_severity</refname> - <refpurpose>Setta il livello minimo di errori critici.</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>void - <function>mssql_min_error_severity</function> - </funcdef> - <paramdef>int <parameter>livello_critico</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsect1> - </refentry> - - <refentry id="function.mssql-min-message-severity"> - <refnamediv> - <refname>mssql_min_message_severity</refname> - <refpurpose>Setta li livello critico minimo di messaggi</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>void - <function>mssql_min_message_severity</function> - </funcdef> - <paramdef>int <parameter>livello_critico</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsect1> - </refentry> - - <refentry id="function.mssql-num-fields"> - <refnamediv> - <refname>mssql_num_fields</refname> - <refpurpose>Restituisce il numero di campi in un risultato</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_num_fields</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione <function>mssql_num_fields</function> restituisce il numero di - campi presenti in un risultato. - </para> - <para> - Vedere anche: <function>mssql_db_query</function>, - <function>mssql_query</function>, - <function>mssql_fetch_field</function>, e - <function>mssql_num_rows</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-num-rows"> - <refnamediv> - <refname>mssql_num_rows</refname> - <refpurpose>Restituisce il numero di righe</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_num_rows</function></funcdef> - <paramdef>string <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione <function>mssql_num_rows</function> restituisce il numero di righe - presenti in un risultato. - </para> - <para> - Vedere anche: <function>mssql_db_query</function>, - <function>mssql_query</function>, e - <function>mssql_fetch_row</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-pconnect"> - <refnamediv> - <refname>mssql_pconnect</refname> - <refpurpose>Apre una connessione persistente con MS SQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_pconnect</function></funcdef> - <paramdef>string - <parameter><optional>nome_server</optional></parameter> - </paramdef> - <paramdef>string - <parameter><optional>nome_utente</optional></parameter> - </paramdef> - <paramdef>string - <parameter><optional>password</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce: o un identificativo di connessione persistente, - o falso se si verifica un errore. - </para> - <para> - La funzione <function>mssql_pconnect</function> agisce come - <function>mssql_connect</function> tranne che per due differenze. - </para> - <para> - Prima differenza, quando si cerca di stabilire la connessione, la funzione - per prima cosa cerca di trovare una connessione ( persistente ) già - aperta verso lo stesso server con i medesimi utenti e password. - Se ne viene trovata una, la funzione restituisce l'identificativo di - quella connessione, invece di stabilirne una nuova. - </para> - <para> - Seconda differenza, la connessione con il server SQL non verrà chiusa - al termine dello script. Il collegamento resterà aperto per utilizzi futuri - (la funzione <function>mssql_close</function> non chiude i collegamenti - aperti da <function>mssql_pconnect</function>). - </para> - <para> - Per questo motivo questo tipo di collegamento viene definito 'persistente'. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-query"> - <refnamediv> - <refname>mssql_query</refname> - <refpurpose>Invia una query a MS SQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_query</function></funcdef> - <paramdef>string <parameter>teso_query</parameter></paramdef> - <paramdef>int - <parameter><optional>id_connessione</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce un identificativo di risultato in caso di esecuzione - corretta, oppure falso in caso di errore. - </para> - <para> - La funzione <function>mssql_query</function> invia una query al database - attivo sul server attraverso la connessione specificata da id_connessione. - Se l'argomento id_connessione non viene fornito, si utilizza l'ultima connessione - aperta in ordine di tempo. Se non vi sono connessioni aperte, - la funzione tenta di stabilire una connessione, come se fosse - utilizzata la funzione <function>mssql_connect</function>, e utilizza - quella. - </para> - <para> - Vedere anche: <function>mssql_db_query</function>, - <function>mssql_select_db</function>, e - <function>mssql_connect</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-result"> - <refnamediv> - <refname>mssql_result</refname> - <refpurpose>Restituisce i dati di un risultato</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_result</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>i</parameter></paramdef> - <paramdef>mixed <parameter>campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce il contenuto della cella ( identificata dalla riga - e dal campo indicato) dal risultato associato a id_risultato. - </para> - <para> - La funzione <function>mssql_result</function> restituisce il contenuto di una - cella da un risultato di una query a MS SQL. - L'argomento campo può essere la posizione di un campo, oppure il suo nome, - oppure nome tabella punto nome campo ( nome_tabella.nome_campo ). Se il nome - della colonna ha un sostituto, ('select foo as bar from...'), usare quello - anzichè il nome originale. - </para> - <para> - Quando si lavora con risultati abbastanza grossi, si dovrebbe considerare - l'utilizzo di funzioni che restituiscono l'intera riga ( indicate di seguito ), - dato che queste restituiscono il contenuto di molte celle in una chiamata sola. - Pertanto sono MOLTO più veloci di <function>mssql_result</function>. - Da notare inoltre, che specificando la posizione per l'argomento campo, la funzione - è molto più veloce rispetto al caso in cui si indica il nome del campo o della tabella. - </para> - <para> - Le alternative più veloci raccomandate sono: - <function>mssql_fetch_row</function>, - <function>mssql_fetch_array</function>, e - <function>mssql_fetch_object</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.mssql-select-db"> - <refnamediv> - <refname>mssql_select_db</refname> - <refpurpose>Seleziona un database MS SQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>mssql_select_db</function></funcdef> - <paramdef>string <parameter>Nome_database</parameter></paramdef> - <paramdef>int - <parameter><optional>id_connessione</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> Restituisce: vero se l'operazione riesce, falso se si verifica un errore. - </para> - <para> - La funzione <function>mssql_select_db</function> setta il database attivo - sul server attraverso la connessione specificata da id_connessione. - Se l'argomento id_connessione non viene fornito, si utilizza l'ultima connessione - aperta in ordine di tempo. Se non vi sono connessioni aperte, - la funzione tenta di stabilire una connessione, come se fosse - utilizzata la funzione <function>mssql_connect</function>, e utilizza - quella. - </para> - <para> - Ciascuna esecuzione di <function>mssql_query</function> sarà - fatta sul database attivo. - </para> - <para> Vedere anche: - <function>mssql_connect</function>, - <function>mssql_pconnect</function>, e - <function>mssql_query</function> - </para> - </refsect1> - </refentry> - -</reference> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> + <reference id="ref.mssql"> + <title>Funzioni per Microsoft SQL Server</title> + <titleabbrev>MS SQL Server</titleabbrev> + + <refentry id="function.mssql-close"> + <refnamediv> + <refname>mssql_close</refname> + <refpurpose>Chiude la connessione con MS SQL Server</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_close</function></funcdef> + <paramdef>int + <parameter><optional>id_connessione</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce: vero se l'operazione riesce, falso se si verifica un errore. + </para> + <para> + La funzione <function>mssql_close</function> chiude la connessione + ad un database MS SQL + Server che è associata all' argomento id_connessione. + Se l' id_connessione non viene indicato, si fa riferimento all'ultima connessione + aperta. + </para> + <para> + Nota: solitamente non è necessario l'uso della funzione, dato che + tutte le connessioni non-persistenti sono chiuse automaticamente al + termine dell'esecuzione dello script. + </para> + <para> + <function>mssql_close</function> non chiude i collegamenti persistenti + aperti utilizzando <function>mssql_pconnect</function>. + </para> + <para> + Vedere anche: <function>mssql_connect</function>, + <function>mssql_pconnect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-connect"> + <refnamediv> + <refname>mssql_connect</refname> + <refpurpose>Apre una connessione con un server MS SQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_connect</function></funcdef> + <paramdef>string + <parameter><optional>nome_server</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>nome_utente</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>password</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce: un identificativo di connessione su l'operazione riesce, + oppure falso se si verifica un errore. + </para> + <para> + La funzione <function>mssql_connect</function> realizza una connessione + con un server MS SQL. L' argomento nome_server deve essere un nome valido + di server come definito nel file 'interfaces'. + </para> + <para> + Qualora la funzione <function>mssql_connect</function> venga eseguita + una seconda volta con i medesimi parametri, non viene realizzata una nuova + connessione, ma, invece, viene restituito l'identificativo della connessione + già aperta. + </para> + <para> + La connessione con il server verrà chiusa non appena lo script terminerà + l'esecuzione, a meno che la connessione non sia già stata chiusa utilizzando + la funzione <function>mssql_close</function>. + </para> + <para> + Vedere anche <function>mssql_pconnect</function>, e + <function>mssql_close</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-data-seek"> + <refnamediv> + <refname>mssql_data_seek</refname> + <refpurpose>Sposta il puntatore di riga interno</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_data_seek</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>numero_riga</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce: vero se l'operazione riesce, falso se si verifica un errore. + </para> + <para> + La funzione <function>mssql_data_seek</function> sposta il puntatore + di riga, interno al risultato associato all'identificativo di risultato, + alla riga indicata dall'argomento numero_riga. La chiamata successiva a + <function>mssql_fetch_row</function> restituirà la riga richiesta. + </para> + <para> + Vedere anche <function>mssql_data_seek</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-fetch-array"> + <refnamediv> + <refname>mssql_fetch_array</refname> + <refpurpose>Restituisce una riga in un array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_fetch_array</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce: un array corrispondente alla riga estratta, oppure + falso se non vi sono più righe. + </para> + <para> + La funzione <function>mssql_fetch_array</function> è un' estensione + della funzione + <function>mssql_fetch_row</function>. Oltre a memorizzare i dati in un array + con indice numerico, la funzione memorizza i dati in un array associativo + in cui la chiave è costituita dal nome del campo. + </para> + <para> + Un aspetto da notare è che la funzione + <function>mssql_fetch_array</function> NON è significativamente più + lenta rispetto a <function>mssql_fetch_row</function>, mentre nel contempo + fornisce funzionalità maggiori. + </para> + <para> + Per ulteriori dettagli vedere anche + <function>mssql_fetch_row</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-fetch-field"> + <refnamediv> + <refname>mssql_fetch_field</refname> + <refpurpose>Restituisce le informazioni di un campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>object <function>mssql_fetch_field</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int + <parameter><optional>offset_campo</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce un oggetto contenente le informazioni sul campo. + </para> + <para> + La funzione <function>mssql_fetch_field</function> può essere utilizzata + per ottenere informazioni sui campi presenti nel risultato di una certa query. + Se non viene specificato l'argomento offset_campo, la funzione restituisce + il campo successivo che non è ancora stato restituito da + <function>mssql_fetch_field</function>. + </para> + <para> + Le proprietà dell'oggetto sono: + </para> + <itemizedlist> + <listitem> + <simpara> + name - nome della colonna. Se la colonna è il risultato di una funzione, questa + proprietà è valorizzata con "computed#N", dove #N è un numero progressivo. + </simpara> + </listitem> + <listitem> + <simpara> + column_source - tabella da cui sono ricavate le colonne + </simpara> + </listitem> + <listitem> + <simpara> + max_length - lunghezza massima della colonna + </simpara> + </listitem> + <listitem> + <simpara> + numeric - 1 se la colonna è numerica + </simpara></listitem> + </itemizedlist> + <para> + Vedere anche <function>mssql_field_seek</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-fetch-object"> + <refnamediv> + <refname>mssql_fetch_object</refname> + <refpurpose>Restituisce una riga come oggetto</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_fetch_object</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce un oggetto le cui proprietà corrispondono alla riga estratta, + oppure falso se non vi sono più righe. + </para> + <para> + La funzione <function>mssql_fetch_object</function> è simile a + <function>mssql_fetch_array</function>, tranne che per una + differenza, la prima restituisce un oggetto, la seconda un array. + Indirettamente questo significa che si può accedere ai dati solo + attraverso il nome dei campi e non tramite il loro offset ( i numeri non + sono dei validi nomi di proprietà ). + </para> + <para> + A livello di velocità il comportamento è simile a + <function>mssql_fetch_array</function>, e quasi veloce come + <function>mssql_fetch_row</function> (la differenza è + insignificante ). + </para> + <para> + Vedere anche <function>mssql_fetch-array</function> and + <function>mssql_fetch-row</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-fetch-row"> + <refnamediv> + <refname>mssql_fetch_row</refname> + <refpurpose>Restituisce una riga come array numerato</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mssql_fetch_row</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce un array che corrisponde alla riga estratta, + oppure falso se non vi sono più righe. + </para> + <para> + La funzione <function>mssql_fetch_row</function> estrae una riga + di dati dal risultato associato all'identificativo di risultato passato. + La riga viene restituita in un array. Ciascuna colonna è memorizzata + in un campo dell'array. Il primo ha indice 0. + </para> + <para> + Esecuzione successive di <function>mssql_fetch_rows</function> restituiscono + le righe successive presenti nel risultato, oppure falso + se non vi sono più righe. + </para> + <para> + Vedere anche <function>mssql_fetch_array</function>, + <function>mssql_fetch_object</function>, + <function>mssql_data_seek</function>, + <function>mssql_fetch_lengths</function>, e + <function>mssql_result</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-field-length"> + <refnamediv> + <refname>mssql_field_length</refname> + <refpurpose>Restituisce la lunghezza di un campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_field_length</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int + <parameter><optional>offset</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + </refsect1> + </refentry> + + <refentry id="function.mssql-field-name"> + <refnamediv> + <refname>mssql_field_name</refname> + <refpurpose>Restituisce il nome di un campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_field_name</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int + <parameter><optional>offset</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + </refsect1> + </refentry> + + <refentry id="function.mssql-field-seek"> + <refnamediv> + <refname>mssql_field_seek</refname> + <refpurpose>Posizionamento sul campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_field_seek</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>offset_campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Si posiziona sul campo richiesto. Eseguendo successivamente la + funzione <function>mssql_fetch_field</function> senza indicare alcun campo, + quest'ultima restituirà il campo richiesto tramite + <function>mssql_fetch_field</function>.</para> + <para></para> + <para> + Vedere anche <function>mssql_fetch_field</function>.</para> + </refsect1> + </refentry> + + <refentry id="function.mssql-field-type"> + <refnamediv> + <refname>mssql_field_type</refname> + <refpurpose>Restituisce il tipo di un campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mssql_field_type</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int + <parameter><optional>offset</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + </refsect1> + </refentry> + + <refentry id="function.mssql-free-result"> + <refnamediv> + <refname>mssql_free_result</refname> + <refpurpose>Libera la memoria di un risultato</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_free_result</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione <function>mssql_free_result</function> permette + di non utilizzare molta memoria durante l'esecuzione di uno script. + Infatti, se si è sicuri di non avere più bisogno dei dati del risultato, + si può eseguire <function>mssql_free_result</function>, e la memoria associata + a <parameter>id_risultato</parameter> sarà liberata. Se la funzione + non viene utilizzata, le aree di memoria resteranno disponibili per tutta + la durata dello script. Al termine verranno liberate in modo automatico. + Tuttavia utilizzando la funzione <function>mssql_free_result</function>, + l'area di memoria del risultato associato a id_risultato, sarà liberata. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-get-last-message"> + <refnamediv> + <refname>mssql_get_last_message</refname> + <refpurpose> + Restituisce l'ultimo messaggio dal server ( oltre min_message_severity?) + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string + <function>mssql_get_last_message</function> + </funcdef> + <paramdef>void <parameter></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsect1> + </refentry> + + <refentry id="function.mssql-min-error-severity"> + <refnamediv> + <refname>mssql_min_error_severity</refname> + <refpurpose>Setta il livello minimo di errori critici.</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>void + <function>mssql_min_error_severity</function> + </funcdef> + <paramdef>int <parameter>livello_critico</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsect1> + </refentry> + + <refentry id="function.mssql-min-message-severity"> + <refnamediv> + <refname>mssql_min_message_severity</refname> + <refpurpose>Setta li livello critico minimo di messaggi</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>void + <function>mssql_min_message_severity</function> + </funcdef> + <paramdef>int <parameter>livello_critico</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsect1> + </refentry> + + <refentry id="function.mssql-num-fields"> + <refnamediv> + <refname>mssql_num_fields</refname> + <refpurpose>Restituisce il numero di campi in un risultato</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_num_fields</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione <function>mssql_num_fields</function> restituisce il numero di + campi presenti in un risultato. + </para> + <para> + Vedere anche: <function>mssql_db_query</function>, + <function>mssql_query</function>, + <function>mssql_fetch_field</function>, e + <function>mssql_num_rows</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-num-rows"> + <refnamediv> + <refname>mssql_num_rows</refname> + <refpurpose>Restituisce il numero di righe</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_num_rows</function></funcdef> + <paramdef>string <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione <function>mssql_num_rows</function> restituisce il numero di righe + presenti in un risultato. + </para> + <para> + Vedere anche: <function>mssql_db_query</function>, + <function>mssql_query</function>, e + <function>mssql_fetch_row</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-pconnect"> + <refnamediv> + <refname>mssql_pconnect</refname> + <refpurpose>Apre una connessione persistente con MS SQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_pconnect</function></funcdef> + <paramdef>string + <parameter><optional>nome_server</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>nome_utente</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>password</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce: o un identificativo di connessione persistente, + o falso se si verifica un errore. + </para> + <para> + La funzione <function>mssql_pconnect</function> agisce come + <function>mssql_connect</function> tranne che per due differenze. + </para> + <para> + Prima differenza, quando si cerca di stabilire la connessione, la funzione + per prima cosa cerca di trovare una connessione ( persistente ) già + aperta verso lo stesso server con i medesimi utenti e password. + Se ne viene trovata una, la funzione restituisce l'identificativo di + quella connessione, invece di stabilirne una nuova. + </para> + <para> + Seconda differenza, la connessione con il server SQL non verrà chiusa + al termine dello script. Il collegamento resterà aperto per utilizzi futuri + (la funzione <function>mssql_close</function> non chiude i collegamenti + aperti da <function>mssql_pconnect</function>). + </para> + <para> + Per questo motivo questo tipo di collegamento viene definito 'persistente'. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-query"> + <refnamediv> + <refname>mssql_query</refname> + <refpurpose>Invia una query a MS SQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_query</function></funcdef> + <paramdef>string <parameter>teso_query</parameter></paramdef> + <paramdef>int + <parameter><optional>id_connessione</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce un identificativo di risultato in caso di esecuzione + corretta, oppure falso in caso di errore. + </para> + <para> + La funzione <function>mssql_query</function> invia una query al database + attivo sul server attraverso la connessione specificata da id_connessione. + Se l'argomento id_connessione non viene fornito, si utilizza l'ultima connessione + aperta in ordine di tempo. Se non vi sono connessioni aperte, + la funzione tenta di stabilire una connessione, come se fosse + utilizzata la funzione <function>mssql_connect</function>, e utilizza + quella. + </para> + <para> + Vedere anche: <function>mssql_db_query</function>, + <function>mssql_select_db</function>, e + <function>mssql_connect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-result"> + <refnamediv> + <refname>mssql_result</refname> + <refpurpose>Restituisce i dati di un risultato</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_result</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>i</parameter></paramdef> + <paramdef>mixed <parameter>campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce il contenuto della cella ( identificata dalla riga + e dal campo indicato) dal risultato associato a id_risultato. + </para> + <para> + La funzione <function>mssql_result</function> restituisce il contenuto di una + cella da un risultato di una query a MS SQL. + L'argomento campo può essere la posizione di un campo, oppure il suo nome, + oppure nome tabella punto nome campo ( nome_tabella.nome_campo ). Se il nome + della colonna ha un sostituto, ('select foo as bar from...'), usare quello + anzichè il nome originale. + </para> + <para> + Quando si lavora con risultati abbastanza grossi, si dovrebbe considerare + l'utilizzo di funzioni che restituiscono l'intera riga ( indicate di seguito ), + dato che queste restituiscono il contenuto di molte celle in una chiamata sola. + Pertanto sono MOLTO più veloci di <function>mssql_result</function>. + Da notare inoltre, che specificando la posizione per l'argomento campo, la funzione + è molto più veloce rispetto al caso in cui si indica il nome del campo o della tabella. + </para> + <para> + Le alternative più veloci raccomandate sono: + <function>mssql_fetch_row</function>, + <function>mssql_fetch_array</function>, e + <function>mssql_fetch_object</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mssql-select-db"> + <refnamediv> + <refname>mssql_select_db</refname> + <refpurpose>Seleziona un database MS SQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mssql_select_db</function></funcdef> + <paramdef>string <parameter>Nome_database</parameter></paramdef> + <paramdef>int + <parameter><optional>id_connessione</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> Restituisce: vero se l'operazione riesce, falso se si verifica un errore. + </para> + <para> + La funzione <function>mssql_select_db</function> setta il database attivo + sul server attraverso la connessione specificata da id_connessione. + Se l'argomento id_connessione non viene fornito, si utilizza l'ultima connessione + aperta in ordine di tempo. Se non vi sono connessioni aperte, + la funzione tenta di stabilire una connessione, come se fosse + utilizzata la funzione <function>mssql_connect</function>, e utilizza + quella. + </para> + <para> + Ciascuna esecuzione di <function>mssql_query</function> sarà + fatta sul database attivo. + </para> + <para> Vedere anche: + <function>mssql_connect</function>, + <function>mssql_pconnect</function>, e + <function>mssql_query</function> + </para> + </refsect1> + </refentry> + +</reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/it/functions/pgsql.xml diff -u phpdoc/it/functions/pgsql.xml:1.9 phpdoc/it/functions/pgsql.xml:1.10 --- phpdoc/it/functions/pgsql.xml:1.9 Sat Jul 7 18:25:06 2001 +++ phpdoc/it/functions/pgsql.xml Sat Jul 7 19:11:34 2001 @@ -1,1208 +1,1208 @@ - <reference id="ref.pgsql"> - <title>Funzioni PostgreSQL</title> - <titleabbrev>PostgreSQL</titleabbrev> - - <partintro> - <para> - Postgres, originariamente sviluppato nel UC Berkeley Computer Science - Department, è stato uno dei pionieri dei concetti object-relational - che ora stanno diventando disponibili in alcuni database commerciali. - Fornisce supporto al linguaggio SQL92/SQL3, all'integrità delle transazioni, - e all'estensibilità del tipo. PostgreSQL è un discendente di dominio pubblico - e Open Source di questo codice Berkeley originale. - </para> - <para> - PostgreSQL è disponibile senza alcun costo. La versione corrente è - disponibile a <ulink url="&url.pgsql;">www.PostgreSQL.org</ulink>. - </para> - <para> - Fin dalla versione 6.3 (03/02/1998) PostgreSQL usa gli unix domain sockets. - La tabella sottostante descrive queste nuove possibilità di connessione. - Questo socket può essere trovato in <filename>/tmp/.s.PGSQL.5432</filename>. - Questa opzione può venire abilitata con la flag '-i' a <command>postmaster - </command> e il suo significato è: "ascolta sui sockets TCP/IP come sugli - Unix domain sockets". - <table> - <title>Postmaster e PHP</title> - <tgroup cols="3"> - <thead> - <row> - <entry>Postmaster</entry> - <entry>PHP</entry> - <entry>Status</entry> - </row> - </thead> - <tbody> - <row> - <entry>postmaster &amp;</entry> - <entry>pg_connect("", "", "", "", "dbname");</entry> - <entry>OK</entry> - </row> - <row> - <entry>postmaster -i &amp;</entry> - <entry>pg_connect("", "", "", "", "dbname");</entry> - <entry>OK</entry> - </row> - <row> - <entry>postmaster &amp;</entry> - <entry>pg_connect("localhost", "", "", "", "dbname");</entry> - <entry> - Impossibile collegarsi al server PostgreSQL: connectDB() failed: - Il postmaster è in esecuzione e accetta connessioni TCP/IP (con -i) - a 'localhost' sulla porta '5432'? in /path/to/file.php3 sulla linea 20. - </entry> - </row> - <row> - <entry>postmaster -i &amp;</entry> - <entry>pg_connect("localhost", "", "", "", "dbname");</entry> - <entry>OK</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - Si può anche stabilire una connessione con il seguete comando: - <command>$conn = pg_Connect("host=localhost port=5432 - dbname=chris");</command> - </para> - <para> - Per usare l'interfaccia large object (lo), è necessario includerla entro - un blocco di una transazione. Un blocco di transazione inizia con un - <command>begin</command> e se la transazione è stata valida termina - con <command>commit</command> e <command>end</command>. Se la - transazione fallisce, essa deve venire chiusa con - <command>rollback</command> e <command>abort</command>. - - <example> - <title>Utilizzare Large Objects</title> - <programlisting role="php"> -&lt;?php - $database = pg_Connect ("", "", "", "", "jacarta"); - pg_exec ($database, "begin"); - $oid = pg_locreate ($database); - echo ("$oid\n"); - $handle = pg_loopen ($database, $oid, "w"); - echo ("$handle\n"); - pg_lowrite ($handle, "gaga"); - pg_loclose ($handle); - pg_exec ($database, "commit"); -?> - </programlisting> - </example> - </para> - </partintro> - - <refentry id="function.pg-close"> - <refnamediv> - <refname>pg_Close</refname> - <refpurpose>chiude una connessione PostgreSQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>pg_close</function></funcdef> - <paramdef>int <parameter>connection</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce falso se connection non è un valido indice di connessione, vero - altrimenti. Chiude la connessione con il database PostgreSQL associato - all'indice di connessione fornito. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-cmdtuples"> - <refnamediv> - <refname>pg_cmdTuples</refname> - <refpurpose>restituisce il numero di tuples interessate</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_cmdtuples</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_cmdTuples</function> restituisce il numero di tuples - (instanze) interessate dalle query INSERT, UPDATE, e DELETE. Se nessuna - tuple è interessata la funzione restituirà 0. - <example> - <title>pg_cmdtuples</title> - <programlisting role="php"> -&lt;?php -$result = pg_exec($conn, "INSERT INTO verlag VALUES ('Autor')"); -$cmdtuples = pg_cmdtuples($result); -echo $cmdtuples . " &lt;- cmdtuples affected."; -?> - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-connect"> - <refnamediv> - <refname>pg_Connect</refname> - <refpurpose>apre una connessione</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_connect</function></funcdef> - <paramdef>string <parameter>host</parameter></paramdef> - <paramdef>string <parameter>port</parameter></paramdef> - <paramdef>string <parameter>options</parameter></paramdef> - <paramdef>string <parameter>tty</parameter></paramdef> - <paramdef>string <parameter>dbname</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce un indice di connessione se la chiamata ha avuto successo, o falso se la connessione - non può essere creata. Apre una connessione ad un database PostgreSQL. - Tutti i parametri devono essere delle quoted string, incluso il numero della porta. - I parametri options e tty sono opzionali e possono essere tralasciati. - Questa funzione ritorna un indice di connessione che è richiesto dalle - altre funzioni di PostgreSQL. Potete avere multiple connessioni aperte - nello stesso momento. - </para> - <para> - Una connessione può essere anche stabilita con il seguente comando: - <command>$conn = pg_connect("dbname=marliese port=5432");</command> - Gli altri parametri oltre <parameter>dbname</parameter> e - <parameter>port</parameter> sono <parameter>host</parameter>, - <parameter>tty</parameter>, <parameter>options</parameter>, - <parameter>user</parameter> e <parameter>password</parameter>. - </para> - <para> - Vedere anche <function>pg_pConnect</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-dbname"> - <refnamediv> - <refname>pg_DBname</refname> - <refpurpose>nome del database</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>pg_dbname</function></funcdef> - <paramdef>int <parameter>connection</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce il nome del database a cui si riferisce l'indice di connessione - PostgreSQL che è stato fornito, o falso se connection non è un valido - indice di connessione. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-errormessage"> - <refnamediv> - <refname>pg_ErrorMessage</refname> - <refpurpose>messaggio di errore</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>pg_errormessage</function></funcdef> - <paramdef>int <parameter>connection</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce una stringa contenente il messaggio di errore, falso se fallise. - Dettagli riguardo l'errore probabilmente non possono essere ottenuti - usando la funzione <function>pg_errormessage</function> se un errore è - avvenuto sull'ultima azione sul database per la quale esiste una - connessione valida, questa funzione ritornerà una stringa contenente - il messaggio di errore generato dal backend server. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-exec"> - <refnamediv> - <refname>pg_Exec</refname> - <refpurpose>esegue una query</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_exec</function></funcdef> - <paramdef>int <parameter>connection</parameter></paramdef> - <paramdef>string <parameter>query</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce un indice di result se la query può venire eseguita, falso - se fallisce o se connection non è un valido indice di connessione. Dettagli - riguardo l'errore possono essere ottenuti usando la funzione - <function>pg_ErrorMessage</function> se connection è - valido. Invia uno statement SQL al database PostgreSQL specificato dall'indice - di connessione. Connection deve essere un indice valido restituito da - <function>pg_Connect</function>. Il valore restituito da questa funzione è un indice - da usarsi per accedere ai result da altre funzioni PostgreSQL. - - <note> - <simpara> - PHP/FI restituiva 1 se dalla query non ci si attendeva alcuna restituzione di dati - (inserimenti o aggiornamenti, ad esempio) e valori maggiori di 1 anche su selezioni - che non ritornavano alcunchè. Nessuna supposizione di questo genere può essere fatta in PHP. - </simpara> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fetch-array"> - <refnamediv> - <refname>pg_Fetch_Array</refname> - <refpurpose>elabora una riga come un vettore</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>pg_fetch_array</function></funcdef> - <paramdef>int <parameter>result</parameter></paramdef> - <paramdef>int <parameter>row</parameter></paramdef> - <paramdef>int - <parameter><optional>result_type</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce: Un vettore che corrisponde alla riga elaborata, o falso - se non ci sono ulteriori righe.</para> - <para> - <function>pg_fetch_array</function> è una versione estesa di - <function>pg_fetch_row</function>. Oltre a salvare i dati - negli indici numerici del vettore del result, essa salva anche i dati - in indici associativi, usando i nomi dei campi come chiavi. - </para> - <para> - Il terzo parametro opzionale <parameter>result_type</parameter> in - - <function>pg_fetch_array</function> è una costante e può assumere i seguenti - valori: PGSQL_ASSOC, PGSQL_NUM, e PGSQL_BOTH. - <note> - <para> - <parameter>Result_type</parameter> è stato aggiunto in PHP 4.0. - </para> - </note> - </para> - <para> - Un'importante cosa da notare è che l'utilizzo di - <function>pg_fetch_array</function> NON è in modo significativo - più lento che usare <function>pg_fetch_row</function>, anche se - fornisce un significativo valore aggiunto. - </para> - <para> - Per ulteriori dettagli, vedere anche - <function>pg_fetch_row</function> - </para> - <example> - <title>elaborazione in un vettore di PostgreSQL</title> - <programlisting role="php"> -&lt;?php -$conn = pg_pconnect("","","","","publisher"); -if (!$conn) { - echo "An error occured.\n"; - exit; -} - -$result = pg_Exec ($conn, "SELECT * FROM authors"); -if (!$result) { - echo "An error occured.\n"; - exit; -} - -$arr = pg_fetch_array ($result, 0); -echo $arr[0] . " &lt;- array\n"; - -$arr = pg_fetch_array ($result, 1); -echo $arr["author"] . " &lt;- array\n"; -?> - </programlisting> - </example> - </refsect1> - </refentry> - - <refentry id="function.pg-fetch-object"> - <refnamediv> - <refname>pg_Fetch_Object</refname> - <refpurpose>elabora una riga come un oggetto</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>object <function>pg_fetch_object</function></funcdef> - <paramdef>int <parameter>result</parameter></paramdef> - <paramdef>int <parameter>row</parameter></paramdef> - <paramdef>int - <parameter><optional>result_type</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce: Un oggetto con proprietà che corrispondono alla riga elaborata, - o falso se non ci sono ulteriori righe. - </para> - <para> - <function>pg_fetch_object</function> è simile a - <function>pg_fetch_array</function>, con una differeza - un - oggetto viene restituito, invece che un vettore. Indirettamente, ciò - significa che potete accedere ai dati solamente tramite i nomi dei campi, - e non tramite il loro offset (i numeri sono invalidi nomi di proprietà). - </para> - <para> - Il terzo parametro opzionale <parameter>result_type</parameter> in - <function>pg_fetch_object</function> è una costante e può assumere i - seguenti valori: PGSQL_ASSOC, PGSQL_NUM, e PGSQL_BOTH. - <note> - <para> - <parameter>Result_type</parameter> è stata aggiunta in PHP 4.0. - </para> - </note> - </para> - <para> - Per ciò che riguarda la velocità, la funzione è identica a - <function>pg_fetch_array</function>, e veloce quasi quanto - <function>pg_fetch_row</function> (la differenza è - insignificante). - </para> - <para> - Vedere anche: <function>pg_fetch_array</function> e - <function>pg_fetch_row</function>. - <example> - <title>elaborazione in un oggetto di Postgres</title> - <programlisting role="php"> -&lt;?php -$database = "verlag"; -$db_conn = pg_connect ("localhost", "5432", "", "", $database); -if (!$db_conn): ?> - &lt;H1>Failed connecting to postgres database &lt;? echo $database ?>&lt;/H1> &lt;? - exit; -endif; - -$qu = pg_exec ($db_conn, "SELECT * FROM verlag ORDER BY autor"); -$row = 0; // postgres needs a row counter other dbs might not - -while ($data = pg_fetch_object ($qu, $row)): - echo $data->autor." ("; - echo $data->jahr ."): "; - echo $data->titel."&lt;BR>"; - $row++; -endwhile; ?> - -&lt;PRE>&lt;?php -$fields[] = Array ("autor", "Author"); -$fields[] = Array ("jahr", " Year"); -$fields[] = Array ("titel", " Title"); - -$row= 0; // postgres needs a row counter other dbs might not -while ($data = pg_fetch_object ($qu, $row)): - echo "----------\n"; - reset ($fields); - while (list (,$item) = each ($fields)): - echo $item[1].": ".$data->$item[0]."\n"; - endwhile; - $row++; -endwhile; -echo "----------\n"; ?> -&lt;/PRE> &lt;?php -pg_freeResult ($qu); -pg_close ($db_conn); -?> - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fetch-row"> - <refnamediv> - <refname>pg_Fetch_Row</refname> - <refpurpose>ottiene una riga come un vettore enumerato</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>pg_fetch_row</function></funcdef> - <paramdef>int <parameter>result</parameter></paramdef> - <paramdef>int <parameter>row</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce: Un vettore che corrisponde alla riga elaborata, o falso - se non ci sono ulteriori righe. - </para> - <para> - <function>pg_fetch_row</function> elabora una riga di dati dal - result associato all'identificatore di result specificato. La riga - viene restituita come un vettore. Ogni colonna del result viene salvata - in un offset del vettore, partendo dall'offset 0. - </para> - <para> - Successive chiamate a <function>pg_fetch_row</function> restituiranno - la riga successiva nel set dei result, o falso se non ci sono ulteriori - righe. - </para> - <para> - Vedere anche: <function>pg_fetch_array</function>, - <function>pg_fetch_object</function>, - <function>pg_result</function>. - <example> - <title>Postgres fetch row</title> - <programlisting role="php"> -&lt;?php -$conn = pg_pconnect("","","","","publisher"); -if (!$conn) { - echo "An error occured.\n"; - exit; -} - -$result = pg_Exec ($conn, "SELECT * FROM authors"); -if (!$result) { - echo "An error occured.\n"; - exit; -} - -$row = pg_fetch_row ($result, 0); -echo $row[0] . " &lt;- row\n"; - -$row = pg_fetch_row ($result, 1); -echo $row[0] . " &lt;- row\n"; - -$row = pg_fetch_row ($result, 2); -echo $row[1] . " &lt;- row\n"; -?> - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fieldisnull"> - <refnamediv> - <refname>pg_FieldIsNull</refname> - <refpurpose>Controlla se un campo è &null;</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_fieldisnull</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - <paramdef>int <parameter>row</parameter></paramdef> - <paramdef>mixed <parameter>field</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Controlla se un campo è nullo o meno. Restituisce 0 se il campo nella - riga data non è &null;. Restituisce 1 se il campo nella riga data è &null;. - Il campo può essere specificato con il suo numero o con il suo nome. La - numerazione delle righe comincia da 0. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fieldname"> - <refnamediv> - <refname>pg_FieldName</refname> - <refpurpose>Restituisce il nome di un campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>pg_fieldname</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - <paramdef>int <parameter>field_number</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_FieldName</function> restituirà il nome del - campo occupante il numero di colonna specificato nel result - associato all'identificatore di result fornito. La numerazione - dei campi comincia da 0. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fieldnum"> - <refnamediv> - <refname>pg_FieldNum</refname> - <refpurpose>Restituisce il numero di una colonna</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_fieldnum</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - <paramdef>string <parameter>field_name</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_FieldNum</function> restituirà il numero dello slot della colonna - che corrisponde al nome del campo nel result associato all'identifitore di result fornito. - La numerazione dei campi comincia da 0. Questa funzione restituisce -1 in caso di errore. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fieldprtlen"> - <refnamediv> - <refname>pg_FieldPrtLen</refname> - <refpurpose>Restituisce la lunghezza stampata</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_fieldprtlen</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - <paramdef>int <parameter>row_number</parameter></paramdef> - <paramdef>string <parameter>field_name</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_FieldPrtLen</function> restituirà l'attuale - lunghezza stampata (numero di caratteri) di uno specifico valore in un - result di PostgreSQL. La numerazione delle righe comincia da 0. Questa - funzione restituisce -1 in caso di errore. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fieldsize"> - <refnamediv> - <refname>pg_FieldSize</refname> - <refpurpose> - Restituisce la capacità interna di memorizzazione del campo specificato - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_fieldsize</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - <paramdef>int <parameter>field_number</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_FieldSize</function> restituirà la capacità interna di - memorizzazione (in byte) del numero del campo nel result di PostgreSQL fornito. - La numerazione dei campi comincia da 0. Una dimensione del campo di -1 - indica un campo a dimensione variabile. Questa funzione restituirà falso - in caso di errore. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-fieldtype"> - <refnamediv> - <refname>pg_FieldType</refname> - <refpurpose> - Restituisce il nome del tipo per il corrispondente numero del campo - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_fieldtype</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - <paramdef>int <parameter>field_number</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_FieldType</function> restituirà una stringa contenente - il nome del tipo del campo nel result di PostgreSQL fornito. - La numerazione dei campi comincia da 0. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-freeresult"> - <refnamediv> - <refname>pg_FreeResult</refname> - <refpurpose>Libera la memoria</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_freeresult</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_FreeResult</function> necessita solo di venire chiamata se - siete preoccupati di stare usando troppa memoria mentre il vostro script - è in esecuzione. Tutta la memoria dei result verrà automaticamente liberata - quando lo script termina. Ma, se siete sicuri che i dati nel result non vi - serviranno più, potete chiamare la <function>pg_FreeResult</function> con - l'identificatore del result come parametro e la memoria associata al result - verrà liberata. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-getlastoid"> - <refnamediv> - <refname>pg_GetLastOid</refname> - <refpurpose>Restituisce l'identificare dell'ultimo oggetto</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_getlastoid</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_GetLastOid</function> può venire usata per ottenere - l'Oid assegnato ad un tuple inserito se l'identificatore del result - è usato dall'ultimo comando inviato via <function>pg_Exec</function> - ed esso era una SQL INSERT. Questa funzione restituirà un intero positivo - se c'era un valido Oid. Restituirà -1 se è avvenuto un errore - o se l'ultimo comando inviato via <function>pg_Exec</function> - non era un INSERT. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-host"> - <refnamediv> - <refname>pg_Host</refname> - <refpurpose>Restituisce il nome dell'host</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>pg_host</function></funcdef> - <paramdef>int <parameter>connection_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_Host</function> restituirà il nome - dell'host a cui è connesso lo specificato identificatore di connessione di PostgreSQL. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-loclose"> - <refnamediv> - <refname>pg_loclose</refname> - <refpurpose>chiude un large object</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>pg_loclose</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_loclose</function> chiude un Inversion Large - Object. <parameter>fd</parameter> è un descrittore di file per il - large object preso da <function>pg_loopen</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-locreate"> - <refnamediv> - <refname>pg_locreate</refname> - <refpurpose>crea un large object</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_locreate</function></funcdef> - <paramdef>int <parameter>conn</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_locreate</function> crea un Inversion Large - Object e restituisce l'oid del large object. - <parameter>conn</parameter> specifica una valida connessione al - database. Le modalità di accesso di PostgreSQL INV_READ, INV_WRITE, e - INV_ARCHIVE non sono supportate, l'oggetto viene creato sempre con - accesso sia in lettura che in scrittura. INV_ARCHIVE è stato rimosso - anche dallo stesso PostgreSQL (versione 6.3 e successive) - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-loexport"> - <refnamediv> - <refname>pg_loexport</refname> - <refpurpose>esporta un large object su un file</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>pg_loexport</function></funcdef> - <paramdef>int - <parameter>oid</parameter> - </paramdef> - <paramdef>int - <parameter>file</parameter> - </paramdef> - <paramdef>int - <parameter><optional>connection_id</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Il parametro <parameter>oid</parameter> specifica l'id dell'oggetto - del large object da esportare e il parametro <parameter>filename</parameter> - specifica il percorso del file. Restituisce &false; se accade un errore, - &true; altrimenti. Ricordate che la gestione di large object in PostgreSQL deve - avvenire all'interno di una transazione. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-loimport"> - <refnamediv> - <refname>pg_loimport</refname> - <refpurpose>importa un large object da un file</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_loimport</function></funcdef> - <paramdef>int - <parameter>file</parameter> - </paramdef> - <paramdef>int - <parameter><optional>connection_id</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Il parametro <parameter>filename</parameter> specifica il percorso - del file che deve essere importato come un large object. Restituisce &false; - se avviene un errore, altrimenti l'id dell'oggetto large object che è stato appena creato. - Ricordate che la gestione di large objects all'interno di PostgreSQL deve - avvenire all'interno di una transazione. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-loopen"> - <refnamediv> - <refname>pg_loopen</refname> - <refpurpose>apre un large object</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_loopen</function></funcdef> - <paramdef>int <parameter>conn</parameter></paramdef> - <paramdef>int <parameter>objoid</parameter></paramdef> - <paramdef>string <parameter>mode</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_loopen</function> apre un Inversion Large Object e - restituisce un descrittore del file del large object. Il descrittore del - file incapsula le informazioni riguardanti la connessione. Non chiudete - la connessione prima di chiudere il descrittore del file del large object. - <parameter>objoid</parameter> specifica un valido large object oid - e <parameter>mode</parameter> può essere "r", "w", o "rw". - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-loread"> - <refnamediv> - <refname>pg_loread</refname> - <refpurpose>legge un large object</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>pg_loread</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>len</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_loread</function> legge al massimo - <parameter>len</parameter> byte da un large object e le restituisce - come una stringa. - <parameter>fd</parameter> specifica un valido descrittore di file di large object - e <parameter>len</parameter> specifica la massima dimensione allocabile - del segmento del large object. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-loreadall"> - <refnamediv> - <refname>pg_loreadall</refname> - <refpurpose>legge un intero large object</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione </title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>pg_loreadall</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_loreadall</function> legge un large object e - lo passa direttamente attraverso il browser, dopo aver inviato tutti - gli header. E' fondamentalmente intesa per inviare dati binari - come immagini e audio. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-lounlink"> - <refnamediv> - <refname>pg_lounlink</refname> - <refpurpose>cancella un large object</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>pg_lounlink</function></funcdef> - <paramdef>int <parameter>conn</parameter></paramdef> - <paramdef>int <parameter>lobjid</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_lounlink</function> elimina un large object con l'identificatore - <parameter>lobjid</parameter> per il large object. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-lowrite"> - <refnamediv> - <refname>pg_lowrite</refname> - <refpurpose>scrive un large object</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_lowrite</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>string <parameter>buf</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_lowrite</function> scrive al massimo su un large object - da una variabile <parameter>buf</parameter> e restituisce il numero - di byte attualmente scritti, o falso in caso di errore. - <parameter>fd</parameter> è un descrittore di file per il large - object da <function>pg_loopen</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-numfields"> - <refnamediv> - <refname>pg_NumFields</refname> - <refpurpose>Restituisce il numero di campi</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_numfields</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_NumFields</function> Restituirà il numero di campi - (colonne) in un result di PostgreSQL. Il parametro è un valido identificatore - di result restituito da <function>pg_Exec</function>. Questa funzione - restituirà -1 in caso di errore. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-numrows"> - <refnamediv> - <refname>pg_NumRows</refname> - <refpurpose>Restituisce il numero di righe</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_numrows</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_NumRows</function> restituirà il numero di righe in un - rusult di PostgreSQL. Il parametro è un valido identificatore di result - restituito da <function>pg_Exec</function>. Questa funzione restituirà -1 in caso di errore. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-options"> - <refnamediv> - <refname>pg_Options</refname> - <refpurpose>Restituisce le opzioni</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>pg_options</function></funcdef> - <paramdef>int <parameter>connection_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_Options</function> restituirà una stringa contenente - le opzioni specificate nella connessione PostgreSQL fornita. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-pconnect"> - <refnamediv> - <refname>pg_pConnect</refname> - <refpurpose> - Crea una connessione persistente al database - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_pconnect</function></funcdef> - <paramdef>string <parameter>host</parameter></paramdef> - <paramdef>string <parameter>port</parameter></paramdef> - <paramdef>string <parameter>options</parameter></paramdef> - <paramdef>string <parameter>tty</parameter></paramdef> - <paramdef>string <parameter>dbname</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce un indice di connessione in caso di successo, o falso - se la connessione non può essere creata. Apre una connessione - persistente a un database PostgreSQL. Ognuno dei parametri deve essere - una quoted string, incluso il numero della porta. I parametri options - e tty sono opzionali e possono essere tralasciati. Questa funzione - restituisce un indice di connessione che è richiesto dalle altre - funzioni PostgreSQL. Potete avere più connessioni persistenti aperte - nello stesso momento. Vedere anche: - <function>pg_Connect</function>. - </para> - <para> - Una connessione può anche essere stabilita con il seguente comando: - <command>$conn = pg_pconnect("dbname=marliese port=5432");</command> - I parametri oltre a <parameter>dbname</parameter> e - <parameter>port</parameter> sono <parameter>host</parameter>, - <parameter>tty</parameter>, <parameter>options</parameter>, - <parameter>user</parameter> e <parameter>password</parameter>. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-port"> - <refnamediv> - <refname>pg_Port</refname> - <refpurpose>Restituisce il numero della porta</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>pg_port</function></funcdef> - <paramdef>int <parameter>connection_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_Port</function> restituirà il numero della porta a cui - si riferisce l'identificatore della connessione PostgreSQL specificata. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-result"> - <refnamediv> - <refname>pg_Result</refname> - <refpurpose>Restituisce valori da un identificatore di result</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>mixed <function>pg_result</function></funcdef> - <paramdef>int <parameter>result_id</parameter></paramdef> - <paramdef>int <parameter>row_number</parameter></paramdef> - <paramdef>mixed <parameter>fieldname</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_Result</function> restituirà valori da un identificatore - di result generato da <function>pg_Exec</function>. <parameter>Row_number</parameter> - e <parameter>fieldname</parameter> specificano quale cella nella tabella - dei risultati deve essere restituita. La numerazione delle righe comincia da 0. - Invece di usare il nome del campo, potete usare l'indice del campo come - numero unquoted. L'indice dei campi inizia da 0. - </para> - <para> - PostgreSQL ha molti tipi predefiniti e solo quelli basilari sono - direttamente supportati qui. Tutti i generi di integer, boolean - e tipi oid sono restituiti come integer. Tutti i generi di float, - e tipi real sono restituiti come valori double. Tutti gli altri tipi, - inclusi i vettori sono restituiti come stringhe formattate nello - stesso modo usato da PostgreSQL che potete vedere nel programma - <command>psql</command>. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-trace"> - <refnamediv> - <refname>pg_trace</refname> - <refpurpose>Traccia una connessione ad un server PostgreSQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>pg_trace</function></funcdef> - <paramdef>string - <parameter>filename</parameter> - </paramdef> - <paramdef>string - <parameter><optional>mode</optional></parameter> - </paramdef> - <paramdef>int - <parameter><optional>connection</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Attiva il tracing delle comunicazioni frontend/backend di PostgreSQL - su un file di debugging. Per comprendere pienamente i risultati è - necessario avere famigliarità con la struttura interna del protocollo - di comunicazione di PostgreSQL. Per chi non la ha, può essere comunque - utile per tracciare errori in query inviate al server, potete ad esempio - fare - 'grep '^To backend' trace.log' e vedere quali query sono state attualmente inviate - al PostgreSQL server. - </para> - <para> - <parameter>filename</parameter> e <parameter>mode</parameter> sono la stessa cosa - come in <function>fopen</function> (<parameter>mode</parameter> è predefinito - a 'w'), <parameter>connection</parameter> specifica la connessione a - trace e usa come predefinita l'ultima aperta. - </para> - <para> - Restituisce &true; se <parameter>filename</parameter> può essere aperto per il - logging, &false; altrimenti. - </para> - <para> - Vedere anche <function>fopen</function> e <function>pg_untrace</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-tty"> - <refnamediv> - <refname>pg_tty</refname> - <refpurpose>Restituisce il nome di tty</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>pg_tty</function></funcdef> - <paramdef>int <parameter>connection_id</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>pg_tty</function> restituirà il nome del tty a cui il server side - debugging output viene inviato sull'identificatore della connessione - PostgreSQL specificata. - </para> - </refsect1> - </refentry> - - <refentry id="function.pg-untrace"> - <refnamediv> - <refname>pg_untrace</refname> - <refpurpose>Ferma il tracing di una connessione ad un server PostgreSQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>bool <function>pg_untrace</function></funcdef> - <paramdef>int - <parameter><optional>connection</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - Ferma il tracing iniziato da <function>pg_trace</function>. - <parameter>connection</parameter> specifica la connessione che è stata - tracciata e usa come predefinita l'ultima aperta. - </para> - <para> - Restituisce sempre &true;. - </para> - <para> - Vedere anche <function>pg_trace</function>. - </para> - </refsect1> - </refentry> - - </reference> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> + <reference id="ref.pgsql"> + <title>Funzioni PostgreSQL</title> + <titleabbrev>PostgreSQL</titleabbrev> + + <partintro> + <para> + Postgres, originariamente sviluppato nel UC Berkeley Computer Science + Department, è stato uno dei pionieri dei concetti object-relational + che ora stanno diventando disponibili in alcuni database commerciali. + Fornisce supporto al linguaggio SQL92/SQL3, all'integrità delle transazioni, + e all'estensibilità del tipo. PostgreSQL è un discendente di dominio pubblico + e Open Source di questo codice Berkeley originale. + </para> + <para> + PostgreSQL è disponibile senza alcun costo. La versione corrente è + disponibile a <ulink url="&url.pgsql;">www.PostgreSQL.org</ulink>. + </para> + <para> + Fin dalla versione 6.3 (03/02/1998) PostgreSQL usa gli unix domain sockets. + La tabella sottostante descrive queste nuove possibilità di connessione. + Questo socket può essere trovato in <filename>/tmp/.s.PGSQL.5432</filename>. + Questa opzione può venire abilitata con la flag '-i' a <command>postmaster + </command> e il suo significato è: "ascolta sui sockets TCP/IP come sugli + Unix domain sockets". + <table> + <title>Postmaster e PHP</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Postmaster</entry> + <entry>PHP</entry> + <entry>Status</entry> + </row> + </thead> + <tbody> + <row> + <entry>postmaster &amp;</entry> + <entry>pg_connect("", "", "", "", "dbname");</entry> + <entry>OK</entry> + </row> + <row> + <entry>postmaster -i &amp;</entry> + <entry>pg_connect("", "", "", "", "dbname");</entry> + <entry>OK</entry> + </row> + <row> + <entry>postmaster &amp;</entry> + <entry>pg_connect("localhost", "", "", "", "dbname");</entry> + <entry> + Impossibile collegarsi al server PostgreSQL: connectDB() failed: + Il postmaster è in esecuzione e accetta connessioni TCP/IP (con -i) + a 'localhost' sulla porta '5432'? in /path/to/file.php3 sulla linea 20. + </entry> + </row> + <row> + <entry>postmaster -i &amp;</entry> + <entry>pg_connect("localhost", "", "", "", "dbname");</entry> + <entry>OK</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + Si può anche stabilire una connessione con il seguete comando: + <command>$conn = pg_Connect("host=localhost port=5432 + dbname=chris");</command> + </para> + <para> + Per usare l'interfaccia large object (lo), è necessario includerla entro + un blocco di una transazione. Un blocco di transazione inizia con un + <command>begin</command> e se la transazione è stata valida termina + con <command>commit</command> e <command>end</command>. Se la + transazione fallisce, essa deve venire chiusa con + <command>rollback</command> e <command>abort</command>. + + <example> + <title>Utilizzare Large Objects</title> + <programlisting role="php"> +&lt;?php + $database = pg_Connect ("", "", "", "", "jacarta"); + pg_exec ($database, "begin"); + $oid = pg_locreate ($database); + echo ("$oid\n"); + $handle = pg_loopen ($database, $oid, "w"); + echo ("$handle\n"); + pg_lowrite ($handle, "gaga"); + pg_loclose ($handle); + pg_exec ($database, "commit"); +?> + </programlisting> + </example> + </para> + </partintro> + + <refentry id="function.pg-close"> + <refnamediv> + <refname>pg_Close</refname> + <refpurpose>chiude una connessione PostgreSQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>pg_close</function></funcdef> + <paramdef>int <parameter>connection</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce falso se connection non è un valido indice di connessione, vero + altrimenti. Chiude la connessione con il database PostgreSQL associato + all'indice di connessione fornito. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-cmdtuples"> + <refnamediv> + <refname>pg_cmdTuples</refname> + <refpurpose>restituisce il numero di tuples interessate</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_cmdtuples</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_cmdTuples</function> restituisce il numero di tuples + (instanze) interessate dalle query INSERT, UPDATE, e DELETE. Se nessuna + tuple è interessata la funzione restituirà 0. + <example> + <title>pg_cmdtuples</title> + <programlisting role="php"> +&lt;?php +$result = pg_exec($conn, "INSERT INTO verlag VALUES ('Autor')"); +$cmdtuples = pg_cmdtuples($result); +echo $cmdtuples . " &lt;- cmdtuples affected."; +?> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-connect"> + <refnamediv> + <refname>pg_Connect</refname> + <refpurpose>apre una connessione</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_connect</function></funcdef> + <paramdef>string <parameter>host</parameter></paramdef> + <paramdef>string <parameter>port</parameter></paramdef> + <paramdef>string <parameter>options</parameter></paramdef> + <paramdef>string <parameter>tty</parameter></paramdef> + <paramdef>string <parameter>dbname</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce un indice di connessione se la chiamata ha avuto successo, o falso se la connessione + non può essere creata. Apre una connessione ad un database PostgreSQL. + Tutti i parametri devono essere delle quoted string, incluso il numero della porta. + I parametri options e tty sono opzionali e possono essere tralasciati. + Questa funzione ritorna un indice di connessione che è richiesto dalle + altre funzioni di PostgreSQL. Potete avere multiple connessioni aperte + nello stesso momento. + </para> + <para> + Una connessione può essere anche stabilita con il seguente comando: + <command>$conn = pg_connect("dbname=marliese port=5432");</command> + Gli altri parametri oltre <parameter>dbname</parameter> e + <parameter>port</parameter> sono <parameter>host</parameter>, + <parameter>tty</parameter>, <parameter>options</parameter>, + <parameter>user</parameter> e <parameter>password</parameter>. + </para> + <para> + Vedere anche <function>pg_pConnect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-dbname"> + <refnamediv> + <refname>pg_DBname</refname> + <refpurpose>nome del database</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>pg_dbname</function></funcdef> + <paramdef>int <parameter>connection</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce il nome del database a cui si riferisce l'indice di connessione + PostgreSQL che è stato fornito, o falso se connection non è un valido + indice di connessione. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-errormessage"> + <refnamediv> + <refname>pg_ErrorMessage</refname> + <refpurpose>messaggio di errore</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>pg_errormessage</function></funcdef> + <paramdef>int <parameter>connection</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce una stringa contenente il messaggio di errore, falso se fallise. + Dettagli riguardo l'errore probabilmente non possono essere ottenuti + usando la funzione <function>pg_errormessage</function> se un errore è + avvenuto sull'ultima azione sul database per la quale esiste una + connessione valida, questa funzione ritornerà una stringa contenente + il messaggio di errore generato dal backend server. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-exec"> + <refnamediv> + <refname>pg_Exec</refname> + <refpurpose>esegue una query</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_exec</function></funcdef> + <paramdef>int <parameter>connection</parameter></paramdef> + <paramdef>string <parameter>query</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce un indice di result se la query può venire eseguita, falso + se fallisce o se connection non è un valido indice di connessione. Dettagli + riguardo l'errore possono essere ottenuti usando la funzione + <function>pg_ErrorMessage</function> se connection è + valido. Invia uno statement SQL al database PostgreSQL specificato dall'indice + di connessione. Connection deve essere un indice valido restituito da + <function>pg_Connect</function>. Il valore restituito da questa funzione è un indice + da usarsi per accedere ai result da altre funzioni PostgreSQL. + + <note> + <simpara> + PHP/FI restituiva 1 se dalla query non ci si attendeva alcuna restituzione di dati + (inserimenti o aggiornamenti, ad esempio) e valori maggiori di 1 anche su selezioni + che non ritornavano alcunchè. Nessuna supposizione di questo genere può essere fatta in PHP. + </simpara> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fetch-array"> + <refnamediv> + <refname>pg_Fetch_Array</refname> + <refpurpose>elabora una riga come un vettore</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>pg_fetch_array</function></funcdef> + <paramdef>int <parameter>result</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + <paramdef>int + <parameter><optional>result_type</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce: Un vettore che corrisponde alla riga elaborata, o falso + se non ci sono ulteriori righe.</para> + <para> + <function>pg_fetch_array</function> è una versione estesa di + <function>pg_fetch_row</function>. Oltre a salvare i dati + negli indici numerici del vettore del result, essa salva anche i dati + in indici associativi, usando i nomi dei campi come chiavi. + </para> + <para> + Il terzo parametro opzionale <parameter>result_type</parameter> in + + <function>pg_fetch_array</function> è una costante e può assumere i seguenti + valori: PGSQL_ASSOC, PGSQL_NUM, e PGSQL_BOTH. + <note> + <para> + <parameter>Result_type</parameter> è stato aggiunto in PHP 4.0. + </para> + </note> + </para> + <para> + Un'importante cosa da notare è che l'utilizzo di + <function>pg_fetch_array</function> NON è in modo significativo + più lento che usare <function>pg_fetch_row</function>, anche se + fornisce un significativo valore aggiunto. + </para> + <para> + Per ulteriori dettagli, vedere anche + <function>pg_fetch_row</function> + </para> + <example> + <title>elaborazione in un vettore di PostgreSQL</title> + <programlisting role="php"> +&lt;?php +$conn = pg_pconnect("","","","","publisher"); +if (!$conn) { + echo "An error occured.\n"; + exit; +} + +$result = pg_Exec ($conn, "SELECT * FROM authors"); +if (!$result) { + echo "An error occured.\n"; + exit; +} + +$arr = pg_fetch_array ($result, 0); +echo $arr[0] . " &lt;- array\n"; + +$arr = pg_fetch_array ($result, 1); +echo $arr["author"] . " &lt;- array\n"; +?> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.pg-fetch-object"> + <refnamediv> + <refname>pg_Fetch_Object</refname> + <refpurpose>elabora una riga come un oggetto</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>object <function>pg_fetch_object</function></funcdef> + <paramdef>int <parameter>result</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + <paramdef>int + <parameter><optional>result_type</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce: Un oggetto con proprietà che corrispondono alla riga elaborata, + o falso se non ci sono ulteriori righe. + </para> + <para> + <function>pg_fetch_object</function> è simile a + <function>pg_fetch_array</function>, con una differeza - un + oggetto viene restituito, invece che un vettore. Indirettamente, ciò + significa che potete accedere ai dati solamente tramite i nomi dei campi, + e non tramite il loro offset (i numeri sono invalidi nomi di proprietà). + </para> + <para> + Il terzo parametro opzionale <parameter>result_type</parameter> in + <function>pg_fetch_object</function> è una costante e può assumere i + seguenti valori: PGSQL_ASSOC, PGSQL_NUM, e PGSQL_BOTH. + <note> + <para> + <parameter>Result_type</parameter> è stata aggiunta in PHP 4.0. + </para> + </note> + </para> + <para> + Per ciò che riguarda la velocità, la funzione è identica a + <function>pg_fetch_array</function>, e veloce quasi quanto + <function>pg_fetch_row</function> (la differenza è + insignificante). + </para> + <para> + Vedere anche: <function>pg_fetch_array</function> e + <function>pg_fetch_row</function>. + <example> + <title>elaborazione in un oggetto di Postgres</title> + <programlisting role="php"> +&lt;?php +$database = "verlag"; +$db_conn = pg_connect ("localhost", "5432", "", "", $database); +if (!$db_conn): ?> + &lt;H1>Failed connecting to postgres database &lt;? echo $database ?>&lt;/H1> &lt;? + exit; +endif; + +$qu = pg_exec ($db_conn, "SELECT * FROM verlag ORDER BY autor"); +$row = 0; // postgres needs a row counter other dbs might not + +while ($data = pg_fetch_object ($qu, $row)): + echo $data->autor." ("; + echo $data->jahr ."): "; + echo $data->titel."&lt;BR>"; + $row++; +endwhile; ?> + +&lt;PRE>&lt;?php +$fields[] = Array ("autor", "Author"); +$fields[] = Array ("jahr", " Year"); +$fields[] = Array ("titel", " Title"); + +$row= 0; // postgres needs a row counter other dbs might not +while ($data = pg_fetch_object ($qu, $row)): + echo "----------\n"; + reset ($fields); + while (list (,$item) = each ($fields)): + echo $item[1].": ".$data->$item[0]."\n"; + endwhile; + $row++; +endwhile; +echo "----------\n"; ?> +&lt;/PRE> &lt;?php +pg_freeResult ($qu); +pg_close ($db_conn); +?> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fetch-row"> + <refnamediv> + <refname>pg_Fetch_Row</refname> + <refpurpose>ottiene una riga come un vettore enumerato</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>pg_fetch_row</function></funcdef> + <paramdef>int <parameter>result</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce: Un vettore che corrisponde alla riga elaborata, o falso + se non ci sono ulteriori righe. + </para> + <para> + <function>pg_fetch_row</function> elabora una riga di dati dal + result associato all'identificatore di result specificato. La riga + viene restituita come un vettore. Ogni colonna del result viene salvata + in un offset del vettore, partendo dall'offset 0. + </para> + <para> + Successive chiamate a <function>pg_fetch_row</function> restituiranno + la riga successiva nel set dei result, o falso se non ci sono ulteriori + righe. + </para> + <para> + Vedere anche: <function>pg_fetch_array</function>, + <function>pg_fetch_object</function>, + <function>pg_result</function>. + <example> + <title>Postgres fetch row</title> + <programlisting role="php"> +&lt;?php +$conn = pg_pconnect("","","","","publisher"); +if (!$conn) { + echo "An error occured.\n"; + exit; +} + +$result = pg_Exec ($conn, "SELECT * FROM authors"); +if (!$result) { + echo "An error occured.\n"; + exit; +} + +$row = pg_fetch_row ($result, 0); +echo $row[0] . " &lt;- row\n"; + +$row = pg_fetch_row ($result, 1); +echo $row[0] . " &lt;- row\n"; + +$row = pg_fetch_row ($result, 2); +echo $row[1] . " &lt;- row\n"; +?> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fieldisnull"> + <refnamediv> + <refname>pg_FieldIsNull</refname> + <refpurpose>Controlla se un campo è &null;</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_fieldisnull</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + <paramdef>mixed <parameter>field</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Controlla se un campo è nullo o meno. Restituisce 0 se il campo nella + riga data non è &null;. Restituisce 1 se il campo nella riga data è &null;. + Il campo può essere specificato con il suo numero o con il suo nome. La + numerazione delle righe comincia da 0. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fieldname"> + <refnamediv> + <refname>pg_FieldName</refname> + <refpurpose>Restituisce il nome di un campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>pg_fieldname</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + <paramdef>int <parameter>field_number</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_FieldName</function> restituirà il nome del + campo occupante il numero di colonna specificato nel result + associato all'identificatore di result fornito. La numerazione + dei campi comincia da 0. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fieldnum"> + <refnamediv> + <refname>pg_FieldNum</refname> + <refpurpose>Restituisce il numero di una colonna</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_fieldnum</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + <paramdef>string <parameter>field_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_FieldNum</function> restituirà il numero dello slot della colonna + che corrisponde al nome del campo nel result associato all'identifitore di result fornito. + La numerazione dei campi comincia da 0. Questa funzione restituisce -1 in caso di errore. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fieldprtlen"> + <refnamediv> + <refname>pg_FieldPrtLen</refname> + <refpurpose>Restituisce la lunghezza stampata</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_fieldprtlen</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + <paramdef>int <parameter>row_number</parameter></paramdef> + <paramdef>string <parameter>field_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_FieldPrtLen</function> restituirà l'attuale + lunghezza stampata (numero di caratteri) di uno specifico valore in un + result di PostgreSQL. La numerazione delle righe comincia da 0. Questa + funzione restituisce -1 in caso di errore. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fieldsize"> + <refnamediv> + <refname>pg_FieldSize</refname> + <refpurpose> + Restituisce la capacità interna di memorizzazione del campo specificato + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_fieldsize</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + <paramdef>int <parameter>field_number</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_FieldSize</function> restituirà la capacità interna di + memorizzazione (in byte) del numero del campo nel result di PostgreSQL fornito. + La numerazione dei campi comincia da 0. Una dimensione del campo di -1 + indica un campo a dimensione variabile. Questa funzione restituirà falso + in caso di errore. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-fieldtype"> + <refnamediv> + <refname>pg_FieldType</refname> + <refpurpose> + Restituisce il nome del tipo per il corrispondente numero del campo + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_fieldtype</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + <paramdef>int <parameter>field_number</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_FieldType</function> restituirà una stringa contenente + il nome del tipo del campo nel result di PostgreSQL fornito. + La numerazione dei campi comincia da 0. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-freeresult"> + <refnamediv> + <refname>pg_FreeResult</refname> + <refpurpose>Libera la memoria</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_freeresult</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_FreeResult</function> necessita solo di venire chiamata se + siete preoccupati di stare usando troppa memoria mentre il vostro script + è in esecuzione. Tutta la memoria dei result verrà automaticamente liberata + quando lo script termina. Ma, se siete sicuri che i dati nel result non vi + serviranno più, potete chiamare la <function>pg_FreeResult</function> con + l'identificatore del result come parametro e la memoria associata al result + verrà liberata. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-getlastoid"> + <refnamediv> + <refname>pg_GetLastOid</refname> + <refpurpose>Restituisce l'identificare dell'ultimo oggetto</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_getlastoid</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_GetLastOid</function> può venire usata per ottenere + l'Oid assegnato ad un tuple inserito se l'identificatore del result + è usato dall'ultimo comando inviato via <function>pg_Exec</function> + ed esso era una SQL INSERT. Questa funzione restituirà un intero positivo + se c'era un valido Oid. Restituirà -1 se è avvenuto un errore + o se l'ultimo comando inviato via <function>pg_Exec</function> + non era un INSERT. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-host"> + <refnamediv> + <refname>pg_Host</refname> + <refpurpose>Restituisce il nome dell'host</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>pg_host</function></funcdef> + <paramdef>int <parameter>connection_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_Host</function> restituirà il nome + dell'host a cui è connesso lo specificato identificatore di connessione di PostgreSQL. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-loclose"> + <refnamediv> + <refname>pg_loclose</refname> + <refpurpose>chiude un large object</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>pg_loclose</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_loclose</function> chiude un Inversion Large + Object. <parameter>fd</parameter> è un descrittore di file per il + large object preso da <function>pg_loopen</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-locreate"> + <refnamediv> + <refname>pg_locreate</refname> + <refpurpose>crea un large object</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_locreate</function></funcdef> + <paramdef>int <parameter>conn</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_locreate</function> crea un Inversion Large + Object e restituisce l'oid del large object. + <parameter>conn</parameter> specifica una valida connessione al + database. Le modalità di accesso di PostgreSQL INV_READ, INV_WRITE, e + INV_ARCHIVE non sono supportate, l'oggetto viene creato sempre con + accesso sia in lettura che in scrittura. INV_ARCHIVE è stato rimosso + anche dallo stesso PostgreSQL (versione 6.3 e successive) + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-loexport"> + <refnamediv> + <refname>pg_loexport</refname> + <refpurpose>esporta un large object su un file</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>pg_loexport</function></funcdef> + <paramdef>int + <parameter>oid</parameter> + </paramdef> + <paramdef>int + <parameter>file</parameter> + </paramdef> + <paramdef>int + <parameter><optional>connection_id</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Il parametro <parameter>oid</parameter> specifica l'id dell'oggetto + del large object da esportare e il parametro <parameter>filename</parameter> + specifica il percorso del file. Restituisce &false; se accade un errore, + &true; altrimenti. Ricordate che la gestione di large object in PostgreSQL deve + avvenire all'interno di una transazione. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-loimport"> + <refnamediv> + <refname>pg_loimport</refname> + <refpurpose>importa un large object da un file</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_loimport</function></funcdef> + <paramdef>int + <parameter>file</parameter> + </paramdef> + <paramdef>int + <parameter><optional>connection_id</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Il parametro <parameter>filename</parameter> specifica il percorso + del file che deve essere importato come un large object. Restituisce &false; + se avviene un errore, altrimenti l'id dell'oggetto large object che è stato appena creato. + Ricordate che la gestione di large objects all'interno di PostgreSQL deve + avvenire all'interno di una transazione. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-loopen"> + <refnamediv> + <refname>pg_loopen</refname> + <refpurpose>apre un large object</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_loopen</function></funcdef> + <paramdef>int <parameter>conn</parameter></paramdef> + <paramdef>int <parameter>objoid</parameter></paramdef> + <paramdef>string <parameter>mode</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_loopen</function> apre un Inversion Large Object e + restituisce un descrittore del file del large object. Il descrittore del + file incapsula le informazioni riguardanti la connessione. Non chiudete + la connessione prima di chiudere il descrittore del file del large object. + <parameter>objoid</parameter> specifica un valido large object oid + e <parameter>mode</parameter> può essere "r", "w", o "rw". + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-loread"> + <refnamediv> + <refname>pg_loread</refname> + <refpurpose>legge un large object</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>pg_loread</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>len</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_loread</function> legge al massimo + <parameter>len</parameter> byte da un large object e le restituisce + come una stringa. + <parameter>fd</parameter> specifica un valido descrittore di file di large object + e <parameter>len</parameter> specifica la massima dimensione allocabile + del segmento del large object. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-loreadall"> + <refnamediv> + <refname>pg_loreadall</refname> + <refpurpose>legge un intero large object</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione </title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>pg_loreadall</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_loreadall</function> legge un large object e + lo passa direttamente attraverso il browser, dopo aver inviato tutti + gli header. E' fondamentalmente intesa per inviare dati binari + come immagini e audio. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-lounlink"> + <refnamediv> + <refname>pg_lounlink</refname> + <refpurpose>cancella un large object</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>pg_lounlink</function></funcdef> + <paramdef>int <parameter>conn</parameter></paramdef> + <paramdef>int <parameter>lobjid</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_lounlink</function> elimina un large object con l'identificatore + <parameter>lobjid</parameter> per il large object. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-lowrite"> + <refnamediv> + <refname>pg_lowrite</refname> + <refpurpose>scrive un large object</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_lowrite</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>string <parameter>buf</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_lowrite</function> scrive al massimo su un large object + da una variabile <parameter>buf</parameter> e restituisce il numero + di byte attualmente scritti, o falso in caso di errore. + <parameter>fd</parameter> è un descrittore di file per il large + object da <function>pg_loopen</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-numfields"> + <refnamediv> + <refname>pg_NumFields</refname> + <refpurpose>Restituisce il numero di campi</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_numfields</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_NumFields</function> Restituirà il numero di campi + (colonne) in un result di PostgreSQL. Il parametro è un valido identificatore + di result restituito da <function>pg_Exec</function>. Questa funzione + restituirà -1 in caso di errore. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-numrows"> + <refnamediv> + <refname>pg_NumRows</refname> + <refpurpose>Restituisce il numero di righe</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_numrows</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_NumRows</function> restituirà il numero di righe in un + rusult di PostgreSQL. Il parametro è un valido identificatore di result + restituito da <function>pg_Exec</function>. Questa funzione restituirà -1 in caso di errore. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-options"> + <refnamediv> + <refname>pg_Options</refname> + <refpurpose>Restituisce le opzioni</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>pg_options</function></funcdef> + <paramdef>int <parameter>connection_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_Options</function> restituirà una stringa contenente + le opzioni specificate nella connessione PostgreSQL fornita. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-pconnect"> + <refnamediv> + <refname>pg_pConnect</refname> + <refpurpose> + Crea una connessione persistente al database + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_pconnect</function></funcdef> + <paramdef>string <parameter>host</parameter></paramdef> + <paramdef>string <parameter>port</parameter></paramdef> + <paramdef>string <parameter>options</parameter></paramdef> + <paramdef>string <parameter>tty</parameter></paramdef> + <paramdef>string <parameter>dbname</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce un indice di connessione in caso di successo, o falso + se la connessione non può essere creata. Apre una connessione + persistente a un database PostgreSQL. Ognuno dei parametri deve essere + una quoted string, incluso il numero della porta. I parametri options + e tty sono opzionali e possono essere tralasciati. Questa funzione + restituisce un indice di connessione che è richiesto dalle altre + funzioni PostgreSQL. Potete avere più connessioni persistenti aperte + nello stesso momento. Vedere anche: + <function>pg_Connect</function>. + </para> + <para> + Una connessione può anche essere stabilita con il seguente comando: + <command>$conn = pg_pconnect("dbname=marliese port=5432");</command> + I parametri oltre a <parameter>dbname</parameter> e + <parameter>port</parameter> sono <parameter>host</parameter>, + <parameter>tty</parameter>, <parameter>options</parameter>, + <parameter>user</parameter> e <parameter>password</parameter>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-port"> + <refnamediv> + <refname>pg_Port</refname> + <refpurpose>Restituisce il numero della porta</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>pg_port</function></funcdef> + <paramdef>int <parameter>connection_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_Port</function> restituirà il numero della porta a cui + si riferisce l'identificatore della connessione PostgreSQL specificata. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-result"> + <refnamediv> + <refname>pg_Result</refname> + <refpurpose>Restituisce valori da un identificatore di result</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>pg_result</function></funcdef> + <paramdef>int <parameter>result_id</parameter></paramdef> + <paramdef>int <parameter>row_number</parameter></paramdef> + <paramdef>mixed <parameter>fieldname</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_Result</function> restituirà valori da un identificatore + di result generato da <function>pg_Exec</function>. <parameter>Row_number</parameter> + e <parameter>fieldname</parameter> specificano quale cella nella tabella + dei risultati deve essere restituita. La numerazione delle righe comincia da 0. + Invece di usare il nome del campo, potete usare l'indice del campo come + numero unquoted. L'indice dei campi inizia da 0. + </para> + <para> + PostgreSQL ha molti tipi predefiniti e solo quelli basilari sono + direttamente supportati qui. Tutti i generi di integer, boolean + e tipi oid sono restituiti come integer. Tutti i generi di float, + e tipi real sono restituiti come valori double. Tutti gli altri tipi, + inclusi i vettori sono restituiti come stringhe formattate nello + stesso modo usato da PostgreSQL che potete vedere nel programma + <command>psql</command>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-trace"> + <refnamediv> + <refname>pg_trace</refname> + <refpurpose>Traccia una connessione ad un server PostgreSQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>pg_trace</function></funcdef> + <paramdef>string + <parameter>filename</parameter> + </paramdef> + <paramdef>string + <parameter><optional>mode</optional></parameter> + </paramdef> + <paramdef>int + <parameter><optional>connection</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Attiva il tracing delle comunicazioni frontend/backend di PostgreSQL + su un file di debugging. Per comprendere pienamente i risultati è + necessario avere famigliarità con la struttura interna del protocollo + di comunicazione di PostgreSQL. Per chi non la ha, può essere comunque + utile per tracciare errori in query inviate al server, potete ad esempio + fare + 'grep '^To backend' trace.log' e vedere quali query sono state attualmente inviate + al PostgreSQL server. + </para> + <para> + <parameter>filename</parameter> e <parameter>mode</parameter> sono la stessa cosa + come in <function>fopen</function> (<parameter>mode</parameter> è predefinito + a 'w'), <parameter>connection</parameter> specifica la connessione a + trace e usa come predefinita l'ultima aperta. + </para> + <para> + Restituisce &true; se <parameter>filename</parameter> può essere aperto per il + logging, &false; altrimenti. + </para> + <para> + Vedere anche <function>fopen</function> e <function>pg_untrace</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-tty"> + <refnamediv> + <refname>pg_tty</refname> + <refpurpose>Restituisce il nome di tty</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>pg_tty</function></funcdef> + <paramdef>int <parameter>connection_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>pg_tty</function> restituirà il nome del tty a cui il server side + debugging output viene inviato sull'identificatore della connessione + PostgreSQL specificata. + </para> + </refsect1> + </refentry> + + <refentry id="function.pg-untrace"> + <refnamediv> + <refname>pg_untrace</refname> + <refpurpose>Ferma il tracing di una connessione ad un server PostgreSQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>pg_untrace</function></funcdef> + <paramdef>int + <parameter><optional>connection</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Ferma il tracing iniziato da <function>pg_trace</function>. + <parameter>connection</parameter> specifica la connessione che è stata + tracciata e usa come predefinita l'ultima aperta. + </para> + <para> + Restituisce sempre &true;. + </para> + <para> + Vedere anche <function>pg_trace</function>. + </para> + </refsect1> + </refentry> + + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> Index: phpdoc/it/functions/uodbc.xml diff -u phpdoc/it/functions/uodbc.xml:1.9 phpdoc/it/functions/uodbc.xml:1.10 --- phpdoc/it/functions/uodbc.xml:1.9 Sat Jul 7 18:25:16 2001 +++ phpdoc/it/functions/uodbc.xml Sat Jul 7 19:11:35 2001 @@ -1,1647 +1,1647 @@ - <reference id="ref.odbc"> - <title>Funzioni ODBC Unificate</title> - <titleabbrev>ODBC</titleabbrev> - <partintro> - <simpara> - In aggiunta al normale supporto ODBC, le funzioni ODBC unificate del - PHP consentono l'accesso a diversi database che hanno preso in prestito - la semantica dell'API ODBC per implementare la loro API. Invece di mantenere - più driver per database che sono tutti pressoché identici, questi driver sono - stati riuniti in un singolo insieme di funzioni ODBC. - </simpara> - <simpara> - I seguenti database sono supportati dalle funzioni ODBC unificate: - <ulink url="&url.adabas;">Adabas D</ulink>, <ulink - url="&url.ibmdb2;">IBM DB2</ulink>, <ulink - url="&url.iodbc;">iODBC</ulink>, <ulink - url="&url.solid;">Solid</ulink>, and <ulink - url="&url.sybase;">Sybase SQL Anywhere</ulink>. - </simpara> -<!-- install.xml has changed, so this link is no longer working - <simpara> - Please see the <link - linkend="database-support-options">Installation on Unix - Systems</link> chapter for more information about configuring PHP - with these databases. - </simpara> ---> - <note> - <simpara> - Nella connessione ai database sopra elencati non vengono coinvolte funzioni - ODBC. Le funzioni che vengono utilizzate per collegarsi nativamente con essi - condividono solamente lo stesso nome e sintassi delle funzioni ODBC. - </simpara> - </note> - </partintro> - - <refentry id="function.odbc-autocommit"> - <refnamediv> - <refname>odbc_autocommit</refname> - <refpurpose>Setta il parametro autocommit</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_autocommit</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>int <parameter><optional>OnOff</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Se non viene fornito il parametro <parameter>OnOff</parameter>, la funzione - restituisce lo stato dell'auto-commit per - <parameter>id_connessione</parameter>. Il valore reso è vero se l'autocommit - è attivo, altrimenti falso se non è attivato oppure si verifica un errore. - </para> - <para> - Se il campo <parameter>OnOff</parameter> è posto a vero, l' auto-commit è abilitato, - se è valorizzato a falso l'autocommit è disabilitato. La funzione restituisce - <literal>vero</literal> se l'operazione riesce, <literal>falso</literal> se si - verifica un errore. - </para> - <para> - Per default, l'autocommit è abilitato. La disabilitazione - dell'autocommit equivale ad iniziare una transazione. - </para> - <simpara> - Vedere inoltre - <function>odbc_commit</function> e - <function>odbc_rollback</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-binmode"> - <refnamediv> - <refname>odbc_binmode</refname> - <refpurpose>Gestione delle colonne di dati binari</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_binmode</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>modalità</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - (Tipi di campi ODBC SQL coinvolti: BINARY, VARBINARY, LONGVARBINARY) - </para> - <itemizedlist> - <listitem> - <simpara> - ODBC_BINMODE_PASSTHRU: Restituzione del dato binario direttamente al client - </simpara> - </listitem> - <listitem> - <simpara> - ODBC_BINMODE_RETURN: restituisce il dato inalterato - </simpara> - </listitem> - <listitem> - <simpara> - ODBC_BINMODE_CONVERT: Conversione in char - </simpara> - </listitem> - </itemizedlist> - <para> - Quando si esegue la conversione da dati binari SQL a dati di tipo char del C, - ciascun byte ( 8 bits) dei dati sorgenti vengono rappresentati da 2 caratteri ASCII. - Questi caratteri sono la rappresentazione ASCII dei numeri nella - loro forma esadecimale. Ad esempio, il valore binario 00000001 è - convertito in <literal>"01"</literal> e il valore binario 11111111 è - convertito come <literal>"FF"</literal>. - <table> - <title>Gestione del tipo LONGVARBINARY </title> - <tgroup cols="3"> - <thead> - <row> - <entry>Modalità</entry> - <entry>impostazione di longreadlen</entry> - <entry>Comportamento</entry> - </row> - </thead> - <tbody> - <row> - <entry>ODBC_BINMODE_PASSTHRU</entry> - <entry>0</entry> - <entry>direttamente al client</entry> - </row> - <row> - <entry>ODBC_BINMODE_RETURN</entry> - <entry>0</entry> - <entry>direttamente al client</entry> - </row> - <row> - <entry>ODBC_BINMODE_CONVERT</entry> - <entry>0</entry> - <entry>direttamente al client</entry> - </row> - <row> - <entry>ODBC_BINMODE_PASSTHRU</entry> - <entry>>0</entry> - <entry>direttamente al client</entry> - </row> - <row> - <entry>ODBC_BINMODE_RETURN</entry> - <entry>>0</entry> - <entry>ritorna inalterato</entry> - </row> - <row> - <entry>ODBC_BINMODE_CONVERT</entry> - <entry>>0</entry> - <entry>ritorna come char</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - Se viene utilizzata la funzione <function>odbc_fetch_into</function>, nei casi - in cui il dato viene inviato direttamente al client, quest'ultima - restituisce una stringa vuota per le colonne binarie. - </para> - <para> - Se l'argomento <parameter>id_risultato</parameter> è valorizzato a <literal>0</literal>, - il settaggio viene applicato come default per i nuovi risultati. - <note> - <simpara> - I valori di default per longreadlen è <literal>4096</literal>, mentre la modalità di - default è <literal>ODBC_BINMODE_RETURN</literal>. La gestione delle colonne - di campi long binary, è anche gestita dalla funzione - <function>odbc_longreadlen</function> - </simpara> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-close"> - <refnamediv> - <refname>odbc_close</refname> - <refpurpose>Chiude una connessione ODBC</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>odbc_close</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>odbc_close</function> chiude la connessione - con il database server associata all'identificativo di connessione - indicato. - <note> - <simpara> - Se ci sono delle transazioni aperte sulla connessione richiesta, la funzione - fallisce. In questo caso la connessione resta aperta. - </simpara> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-close-all"> - <refnamediv> - <refname>odbc_close_all</refname> - <refpurpose>Chiude tutte le connessioni ODBC</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>void <function>odbc_close_all</function></funcdef> - <void/> - </funcprototype> - </funcsynopsis> - <para> - <function>odbc_close_all</function>chiude tutte le connessioni - aperte con il database server - <note> - <simpara> - Se ci sono delle transazioni aperte sulla connessione richiesta, la funzione - fallisce. In questo caso la connessione resta aperta. - </simpara> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-commit"> - <refnamediv> - <refname>odbc_commit</refname> - <refpurpose>Esegue una transazione ODBC</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_commit</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce: <literal>vero</literal> per operazione corretta, - <literal>falso</literal> se si verifica un errore. Sono eseguite tutte le - transazioni pendenti sulla connessione indicata dall'argomento <parameter>id_connessione</parameter>. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-connect"> - <refnamediv> - <refname>odbc_connect</refname> - <refpurpose>Apre una connessione con una fonte di dati</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_connect</function></funcdef> - <paramdef>string <parameter>dsn</parameter></paramdef> - <paramdef>string <parameter>utente</parameter></paramdef> - <paramdef>string <parameter>password</parameter></paramdef> - <paramdef>int <parameter><optional>tipo_cursore</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce un identificatore di connessione ODBC oppure 0 (<literal>falso</literal>) - se si verifica un errore. - </para> - <simpara> - L'identificatore di connessione ritornato da questa funzione è - utilizzato dalle altre funzioni ODBC. Si possono avere più connessioni - aperte contemporaneamente. Il quarto parametro ( opzionale ), setta - il tipo di cursore da utilizzare per questa connessione. Normalmente - questo parametro non è necessario, ma può essere utilizzato per aggirare - dei problemi che si manifestano con alcuni driver ODBC. - </simpara> - <simpara> - Con alcuni driver ODBC, l'esecuzione di complesse procedure può - generare un errore tipo: "Non si riesce ad aprire un cursore sulla - procedura che richieda qualsiasi cosa oltre ad un singola istruzione - select". L'uso di SQL_CUR_USE_ODBC, può evitare questo errore. Inoltre - alcuni driver non supportano il parametro row_number della funzione - <function>odbc_fetch_row</function>. In questo caso SQL_CUR_USE_ODBC - può essere d'aiuto. - </simpara> - <simpara> - Il campo tipo_cursore può assumere le seguenti costanti: - </simpara> - <para> - <itemizedlist> - <listitem> - <simpara> - SQL_CUR_USE_IF_NEEDED - </simpara> - </listitem> - <listitem> - <simpara> - SQL_CUR_USE_ODBC - </simpara> - </listitem> - <listitem> - <simpara> - SQL_CUR_USE_DRIVER - </simpara> - </listitem> - <listitem> - <simpara> - SQL_CUR_DEFAULT - </simpara></listitem> - </itemizedlist> - </para> - <simpara> - Per le connessioni persistenti vedere - <function>odbc_pconnect</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-cursor"> - <refnamediv> - <refname>odbc_cursor</refname> - <refpurpose>Restituisce il nome del cursore</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>odbc_cursor</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - odbc_cursor restituisce il nome del cursore per l'argomento id_risultato. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-do"> - <refnamediv> - <refname>odbc_do</refname> - <refpurpose>Sinonimo di <function>odbc_exec</function></refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_do</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter>query</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>odbc_do</function> esegue una query sulla connessione - data. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-exec"> - <refnamediv> - <refname>odbc_exec</refname> - <refpurpose>Prepara ed esegue una espressione SQL</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_exec</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter>testo_query</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce <literal>falso</literal> se si verifica un errore. Restituisce - un identificatore del risultato se l'espressione SQL viene - eseguita correttamente. - </para> - <para> - <function>odbc_exec</function> invia una espressione SQL - al server tramite la connessione specificata da - <parameter>id_connessione</parameter>. Questo parametro deve essere - un identificativo valido restituito da - <function>odbc_connect</function> oppure - <function>odbc_pconnect</function>. - </para> - <simpara> - Vedere anche: <function>odbc_prepare</function> ed - <function>odbc_execute</function> per l'esecuzione di molteplici - espressioni SQL. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-execute"> - <refnamediv> - <refname>odbc_execute</refname> - <refpurpose>Esecuzione di un'espressione memorizzata</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_execute</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>array - <parameter><optional>array_parametri</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esegue una espressione SQL memorizzata tramite la funzione - <function>odbc_prepare</function>. Restituisce - <literal>vero</literal> se l'esecuzione riesce, - <literal>falso</literal> in caso negativo. L'array - <parameter>array_parametri</parameter> occorre soltanto - se è necessario fornire parametri all'espressione. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-fetch-into"> - <refnamediv> - <refname>odbc_fetch_into</refname> - <refpurpose>Scarica una riga del risultato della query in un array</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_fetch_into</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter><optional>numero_riga</optional></parameter></paramdef> - <paramdef>array <parameter>array_dati</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione restituisce il numero di colonne presenti nel risultato; - <literal>falso</literal> se si verifica un errore. - Il parametro <parameter>array_dati</parameter> deve essere passato per referenza, - ma può essere di qualsiasi tipo dato che verrà convertito - in array. Nell'array saranno posti i valori delle colonne di una riga tratta dalla tabella - risultante dalla query a partire dall'indice 0. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-fetch-row"> - <refnamediv> - <refname>odbc_fetch_row</refname> - <refpurpose>Estrae una riga</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_fetch_row</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter><optional>numero_riga</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Se <function>odbc_fetch_row</function> ha successo ( c'è almeno - una riga), la funzione restituisce <literal>vero</literal>. Altrimenti, se non vi sono più - righe, la funzione restituisce <literal>falso</literal>. - </para> - <para> - <function>odbc_fetch_row</function> estrae un record dai dati - restituiti dalle funzioni <function>odbc_do</function> / - <function>odbc_exec</function>. Dopo l'esecuzione di - <function>odbc_fetch_row</function>, i campi della riga sono - accessibili tramite la funzione <function>odbc_result</function>. - </para> - <para> - Se non viene specificato il parametro <parameter>numero_riga</parameter>, - <function>odbc_fetch_row</function> restituisce la riga successiva dal set - delle righe risultanti dalla query. Si può intercalare esecuzioni - successive di <function>odbc_fetch_row</function> con e senza il parametro - <parameter>numero_riga</parameter>. - </para> - <para> - Per spostarsi attraverso le righe risultanti, si può eseguire - <function>odbc_fetch_row</function> con il parametro - <parameter>numero_riga</parameter> impostato a 1, e quindi continuare - ad utilizzare <function>odbc_fetch_row</function> senza - <parameter>numero_riga</parameter>. Se il driver non supporta - l'estrazione di una riga per numero, il campo - <parameter>numero_riga</parameter> sarà ignorato. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-field-name"> - <refnamediv> - <refname>odbc_field_name</refname> - <refpurpose>Restituisce il nome della colonna</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>odbc_field_name</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>numero_campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione <function>odbc_field_name</function> restituisce il nome - del campo presente nella colonna richiesta all'interno di un risultato ODBC - identificato dal'argomento id_risultato. La numerazione delle colonne parte da 1. - La funzione restituisce <literal>falso</literal> se si verifica un errore. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-field-num"> - <refnamediv> - <refname>odbc_field_num</refname> - <refpurpose>Restituisce il numero di colonna</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_field_num</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>string <parameter>nome_campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>odbc_field_num</function> restituisce il numero della colonna - in cui si trova il campo richiesto all'interno di un risultato ODBC indicato - dall'argomento id_risultato. La numerazione delle colonne - parte da 1. - Si ottiene <literal>falso</literal> se si verifica un errore. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-field-type"> - <refnamediv> - <refname>odbc_field_type</refname> - <refpurpose>Tipo di campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>odbc_field_type</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>numero_campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione <function>odbc_field_type</function> restituisce il tipo - di dato SQL del campo indicato dal numero all'interno di un set di righe - referenziate dall'identificativo di risultato ODBC passato. - La numerazione delle colonne parte da 1. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-field-len"> - <refnamediv> - <refname>odbc_field_len</refname> - <refpurpose>Restituisce la dimensione (precisione) di un campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_field_len</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>numero_campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - All'interno di un set di righe, referenziate dall'identificativo - di risultato ODBC fornito, la funzione <function>odbc_field_len</function> - restituisce la dimensione ( precisione ) del campo indicato dall'argomento - <parameter>numero_campo</parameter>. La numerazione dei campi parte da 1. - </para> - <simpara> - Vedere anche: <function>odbc_field_scale</function> per ottenere la scala di - un numero in virgola mobile. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-field-precision"> - <refnamediv> - <refname>odbc_field_precision</refname> - <refpurpose>Sinonimo di <function>odbc_field_len</function></refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>odbc_field_precision</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>numero_campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - All'interno di un set di righe, referenziate dall'identificativo - di risultato ODBC fornito, la funzione <function>odbc_field_precision</function> - restituisce la precisione del campo indicato dal numero di campo indicato. - </para> - <para> - Vedere anche: <function>odbc_field_scale</function> per ottenere la scala di - un numero in virgola mobile. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-field-scale"> - <refnamediv> - <refname>odbc_field_scale</refname> - <refpurpose>Restituisce la scala di un campo</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>odbc_field_scale</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>int <parameter>numero_campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - All'interno di un set di righe, referenziate dall'identificativo - di risultato ODBC fornito, la funzione <function>odbc_field_precision</function> - restituisce la scala del campo indicato dal numero di campo indicato. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-free-result"> - <refnamediv> - <refname>odbc_free_result</refname> - <refpurpose>Libera le risorse associate ad un risultato</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_free_result</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce sempre <literal>vero</literal>. - </para> - <para> - La funzione <function>odbc_free_result</function> permette - di non utilizzare molta memoria durante l'esecuzione di uno script. - Infatti, se si è sicuri di non avere più bisogno dei dati del risultato, - si può eseguire <function>odbc_free_result</function>, e la memoria associata - a <parameter>id_risultato</parameter> sarà liberata. Se la funzione - non viene utilizzata, le aree di memoria resteranno disponibili per tutta - la durata dello script. Al termine verranno liberate in modo automatico. - </para> - <para> - <note> - <simpara> - Se si ha l'autocommit disabilitato (vedere - <function>odbc_autocommit</function>) e si esegue - <function>odbc_free_result</function> prima di eseguire il commit, tutte le - transazioni pendenti saranno annullate, - </simpara> - </note> - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-longreadlen"> - <refnamediv> - <refname>odbc_longreadlen</refname> - <refpurpose>Gestione di colonne LONG</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_longreadlen</function></funcdef> - <paramdef>int <parameter>id_risultato </parameter></paramdef> - <paramdef>int <parameter>lunghezza</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - (tipi di campi ODBC ed SQL coinvolti: LONG, LONGVARBINARY) Tramite - l'argomento lunghezza si controlla il numero di byte da ritornare a PHP. - Se il campo viene posto a 0, i dati della colonna saranno passati - direttamente al client. - </para> - <note> - <simpara> - Per la gestione delle colonne di tipo LONGVARBINARY si utilizza anche - <function>odbc_binmode</function>. - </simpara> - </note> - </refsect1> - </refentry> - - <refentry id="function.odbc-num-fields"> - <refnamediv> - <refname>odbc_num_fields</refname> - <refpurpose>Numero di colonne in un esito</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_num_fields</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - All'interno di un set di righe, referenziate dall'identificativo - di risultato ODBC fornito, la funzione <function>odbc_num_fields</function> - restituisce il numero di campi (colonne) presenti. La funzione restituisce -1 se vi - è un errore. L'argomento fornito è un identificatore di esito restituito - dalla funzione <function>odbc_exec</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-pconnect"> - <refnamediv> - <refname>odbc_pconnect</refname> - <refpurpose>Apre una connessione persistente verso un database</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_pconnect</function></funcdef> - <paramdef>string <parameter>dsn</parameter></paramdef> - <paramdef>string <parameter>utente</parameter></paramdef> - <paramdef>string <parameter>password</parameter></paramdef> - <paramdef>int <parameter><optional>tipo_cursore</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce un identificatore di connessione ODBC oppure 0 (<literal>falso</literal>) - su errore. Questa funzione è molto simile a <function>odbc_connect</function>, - eccetto che la connessione non viene realmente chiusa quando - lo script finisce. Future richieste di connessione che utilizzino la - stessa combinazione di <parameter>dsn</parameter>, - <parameter>utente</parameter>, <parameter>password</parameter> - (eseguite sia utilizzando <function>odbc_connect</function>, sia utilizzando - <function>odbc_pconnect</function>) possono riutilizzare la connessione. - </para> - <para> - <note> - <simpara> - Le connessioni persistenti non hanno effetti se PHP viene utilizzato - come programma CGI. - </simpara> - </note> - </para> - <para> - Per informazioni sul campo opzionale tipo_cursore, vedere la funzione - <function>odbc_connect</function>. Per maggiori dettagli sulle - connessioni persistenti, fare riferimento alla FAQ di PHP. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-prepare"> - <refnamediv> - <refname>odbc_prepare</refname> - <refpurpose>Predispone un'espressione all'esecuzione</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_prepare</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter>testo_query</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione ritorna <literal>falso</literal> su errore. - </para> - <para> - Restituisce un identificativo di risultato ODBC se l'espressione SQL - viene predisposta correttamente. L'identificativo restituito può essere - utilizzato successivamente per eseguire l'espressione utilizzando - la funzione <function>odbc_execute</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-num-rows"> - <refnamediv> - <refname>odbc_num_rows</refname> - <refpurpose>Numero di righe in un risultato</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_num_rows</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>odbc_num_rows</function> ritorna il numero di record - presenti in un risultato ODBC. La funzione ritorna -1 se si verifica un errore. - Per le clausole INSERT, UPDATE e DELETE, - <function>odbc_num_rows</function> ritorna il numero di righe - coinvolte. Nella clausola SELECT questo <literal>può</literal> essere - il numero di righe disponibili. - </para> - <para> - Nota: Con diversi driver, la funzione <function>odbc_num_rows</function>, utilizzata con - lo scopo di determinare il numero di righe dopo una SELECT, restituisce -1. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-result"> - <refnamediv> - <refname>odbc_result</refname> - <refpurpose>Restituisce il contenuto dei campi</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>odbc_result</function></funcdef> - <paramdef>int <parameter>id_risultato</parameter></paramdef> - <paramdef>mixed <parameter>campo</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce il contenuto dei campi. - </para> - <para> - Il parametro <parameter>campo</parameter> può essere sia un intero - indicante il numero di colonna del campo desiderato; sia una stringa - contenente il nome del campo. Ad esempio: - <informalexample><programlisting> -$item_3 = odbc_result ($Query_ID, 3); -$item_val = odbc_result ($Query_ID, "val"); - </programlisting> - </informalexample> - </para> - <para> - Nel primo caso l'esecuzione di <function>odbc_result</function> - restituisce il terzo campo del record corrente. - Nel secondo, la funzione <function>odbc_result</function> restituisce il valore - del campo il cui nome è "val", sempre utilizzando i dati dal record corrente. - Si ha un errore qualora il numero di colonna fornito sia minore di 1 - oppure sia superiore al numero delle colonne ( o campi ) presenti - nel record corrente. Analogamente, si ottiene un errore se il nome del campo - richiesto non sia presente nella tabella/e oggetto della ricerca. - </para> - <para> - L'indice dei campi parte da 1. Per quanto riguarda la gestione dei campi - di tipo binario o long fare riferimento a <function>odbc_binmode - </function> e a <function>odbc_longreadlen</function>. - -<!-- - -Se il campo richiesto contiene dati binari o - è un campo di tipo LONG, più lungo di 4096 bytes, - il contenuto non viene restituito, ma invece viene - inviato direttamente al client. - Se si ha necessità di avere restituiti i dati binari, utilizzare - la funzione SQL HEX(), in modo da ottenere i dati del campo in - notazione esadecimale. Ad esempio: "SELECT - HEX(binary_col) FROM mytable" ---> - - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-result-all"> - <refnamediv> - <refname>odbc_result_all</refname> - <refpurpose>Visualizza il risultato in una tabella HTML</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_result_all</function></funcdef> - <paramdef>int <parameter>id_esito</parameter></paramdef> - <paramdef>string <parameter><optional>formato</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce il numero di righe elaborate, oppure - <literal>falso</literal> se si verifica un errore. - </para> - <para> - Dato un identificatore di risultato restituito da <function>odbc_exec</function>, - la funzione <function>odbc_result_all</function> visualizza tutti i record - ottenuti in una di tabella in formato HTML. - Utilizzando il parametro opzionale <parameter>formato</parameter>, è possibile - fornire informazioni addizionali sulla formattazione della tabella. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-rollback"> - <refnamediv> - <refname>odbc_rollback</refname> - <refpurpose>Annulla una transazione</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_rollback</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Annulla tutte le operazioni pendenti sulla connessione indicata - da <parameter>id_connessione</parameter>. Se ha successo ritorna - <literal>vero</literal>, altrimenti <literal>falso</literal>. - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-setoption"> - <refnamediv> - <refname>odbc_setoption</refname> - <refpurpose> - Settaggio dei parametri ODBC. Restituisce falso se si verifica un errore, altrimenti vero. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_setoption</function></funcdef> - <paramdef>int <parameter>identificativo</parameter></paramdef> - <paramdef>int <parameter>funzione</parameter></paramdef> - <paramdef>int <parameter>opzione</parameter></paramdef> - <paramdef>int <parameter>parametro</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Questa funzione permette di manipolare i parametri ODBC per - la connessione o il risultato di una query indicati. La funzione è stata - sviluppata per permettere di aggirare dei problemi emersi in alcuni - driver ODBC. Pertanto si dovrebbe utilizzare questa funzione soltanto se si è - dei programmatori e si conoscono gli effetti generati dalle varie - opzioni. Dato che ogni singola versione di driver ODBC supporta differenti - parametri, occorre avere a disposizione un buon manuale del - driver per avere esposti tutti i differenti settaggi che possono - essere utilizzati. - </para> - <para> - Poiché i parametri possono variare in base al driver ODBC, è fortemente sconsigliato - l'uso di questa funzione in script resi pubblici. Inoltre, - alcune opzioni di ODBC non sono gestibili da questa funzione, - dato che devono essere specificate prima di stabilire la - connessione o prima della preparazione della query. - </para> - <para> - Il campo <parameter>identificativo</parameter> indica la connessione - o l'esito su cui si varia il settaggio. Per la funzione SQLSetConnectOption(), - questo indica l'identificativo di connessione, per SQLSetStmtOption(), - indica l'identificativo del risultato. - </para> - <para> - Il campo <parameter>funzione</parameter> indica quale funzione ODBC - utilizzare. Dovrebbe essere valorizzato a 1 per SQLSetConnectOption() - e a 2 per SQLSetStmtOption(). - </para> - <para> - Il parametro <parameter>opzione</parameter> indica l'opzione da settare.</para> - <para> - Il campo <parameter>parametro</parameter> indica il valore per - l'<parameter>opzione</parameter> richiesta. - <example> - <title>Esempi di utilizzo </title> - <programlisting role="php"> -// 1. Il valore 102 per il campo opzione in SQLSetConnectOption() indica SQL_AUTOCOMMIT. -// Il valore 1 per SQL_AUTOCOMMIT è SQL_AUTOCOMMIT_ON. -// Pertanto questo esempio ha il medesimo effetto di: -// odbc_autocommit($conn, true); - -odbc_setoption ($conn, 1, 102, 1); - -// 2. Il valore 0 per il campo opzione in SQLSetStmtOption() indica SQL_QUERY_TIMEOUT. -// In questo esempio si setta il timeout di una query a 30 secondi. - -$result = odbc_prepare ($conn, $sql); -odbc_setoption ($result, 2, 0, 30); -odbc_execute ($result); - </programlisting> - </example> - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-tables"> - <refnamediv> - <refname>odbc_tables</refname> - <refpurpose> - Restituisce l'elenco delle tabelle presenti in una specifica - sorgente di dati. Restituisce l'identificatore di risultato in cui - vi sono le informazioni. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_tables</function></funcdef> - <paramdef>int <parameter>Id_connessione</parameter></paramdef> - <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> - <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> - <paramdef>string <parameter><optional>nome</optional></parameter></paramdef> - <paramdef>string <parameter><optional>tipo</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione elenca tutte le tabelle presenti nei limiti richiesti. Restituisce un identificatore - di risultato oppure <literal>falso</literal> se si verifica un errore. - </para> - <para> - Le righe risultanti hanno i seguenti campi: - <itemizedlist> - <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>TABLE_OWNER</simpara></listitem> - <listitem><simpara>TABLE_NAME</simpara></listitem> - <listitem><simpara>TABLE_TYPE</simpara></listitem> - <listitem><simpara>REMARKS</simpara></listitem> - </itemizedlist> - </para> - <simpara> - I campi di ordinamento delle righe risultanti sono TABLE_TYPE, TABLE_QUALIFIER, - TABLE_OWNER e TABLE_NAME. - </simpara> - <para> - Gli argomenti <parameter>proprietario</parameter> e <parameter>nome</parameter> - accettano dei criteri di ricerca ('%' per indicare zero o più - caratteri e '_' per indicare un singolo carattere). - </para> - <para> - Per supportare l'enumerazione delle qualifiche, dei proprietari, - e dei tipi tabelle, è stata predisposta la seguente semantica per i - campi <parameter>qualifica</parameter>, <parameter>proprietario</parameter>, - <parameter>nome</parameter>, e <parameter>tipo</parameter>: - <itemizedlist> - <listitem> - <simpara> - Se l'argomento <parameter>qualifica</parameter> è valorizzato - con il carattere percento (%) e i parametri <parameter>proprietario</parameter> - e <parameter>nome</parameter> sono delle stringhe vuote, il risultato sarà - un set di righe contenente la lista delle qualifiche previste per - la sorgente di dati. ( Tutte le colonne tranne TABLE_QUALIFIER conterranno - NULLs.) - </simpara> - </listitem> - <listitem> - <simpara> - Se l'argomento <parameter>proprietario</parameter> è valorizzato - con il carattere percento (%) e i parametri <parameter>qualifica</parameter> - e <parameter>nome</parameter> sono delle stringhe vuote, il risultato sarà - un set di righe contenente la lista dei proprietari previsti per - la sorgente di dati. ( Tutte le colonne tranne TABLE_OWNER conterranno - NULLs.) - </simpara> - </listitem> - <listitem> - <simpara> - Se l'argomento <parameter>tipo</parameter> è valorizzato - con il carattere percento (%) e i parametri <parameter>qualifica</parameter>, - <parameter>proprietario</parameter> e <parameter>nome</parameter> - sono delle stringhe vuote, il risultato sarà - un set di righe contenente la lista dei tipi di tabella previsti per - la sorgente di dati. ( Tutte le colonne tranne TABLE_TYPE conterranno - NULLs.) - </simpara> - </listitem> - </itemizedlist> - </para> - <para> - Se l'argomento <parameter>tipo</parameter> non è una stinga vuota, deve - contenere l'elenco dei tipi interessati separati dalla virgola; - ogni singolo valore può essere, o meno, racchiuso tra apici singoli ('). - Ad esempio: "'TABLE','VIEW'" o "TABLE, VIEW" sono valori validi. - Se la sorgente di dati non supporta alcuni dei tipi di tabelle specificati, - per questi, la funzione <function>odbc_tables</function> non riporta alcuna - informazione. - </para> - <simpara> - Vedere inoltre <function>odbc_tableprivileges</function> per ottenere i - privilegi associati alla tabella. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-tableprivileges"> - <refnamediv> - <refname>odbc_tableprivileges</refname> - <refpurpose> - Elenca le tabelle ed i privilegi ad esse associati. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_tableprivileges</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> - <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> - <paramdef>string <parameter><optional>nome</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Elenca le tabelle presenti nei limiti richiesti e, per ciascuna di queste, - ne fornisce i privilegi. La funzione ritorna un identificatore di risultato ODBC, - oppure <literal>falso</literal> su errore. - </para> - <para> - Le righe risultanti dall'elaborazione hanno i seguenti campi: - <itemizedlist> - <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>TABLE_OWNER</simpara></listitem> - <listitem><simpara>TABLE_NAME</simpara></listitem> - <listitem><simpara>GRANTOR</simpara></listitem> - <listitem><simpara>GRANTEE</simpara></listitem> - <listitem><simpara>PRIVILEGE</simpara></listitem> - <listitem><simpara>IS_GRANTABLE</simpara></listitem> - </itemizedlist> - </para> - <simpara> - I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, TABLE_OWNER e - TABLE_NAME. - </simpara> - <para> - Gli argomenti <parameter>proprietario</parameter> e <parameter>nome</parameter> - accettano dei criteri di ricerca ('%' per indicare zero o più - caratteri e '_' per indicare un singolo carattere). - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-columns"> - <refnamediv> - <refname>odbc_columns</refname> - <refpurpose> - Elenca i nomi delle colonne nella tabella specificata. La funzione - ritorna un identificatore di risultato contenenti le informazioni. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_columns</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> - <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> - <paramdef>string <parameter><optional>nome_tabella</optional></parameter></paramdef> - <paramdef>string <parameter><optional>nome_colonna</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Elenca i nomi di tutte le colonne presenti nei limiti richiesti. - La funzione restituisce un identificatore di risultato - oppure &false; se si verifica un errore. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>TABLE_OWNER</simpara></listitem> - <listitem><simpara>TABLE_NAME</simpara></listitem> - <listitem><simpara>COLUMN_NAME</simpara></listitem> - <listitem><simpara>DATA_TYPE</simpara></listitem> - <listitem><simpara>TYPE_NAME</simpara></listitem> - <listitem><simpara>PRECISION</simpara></listitem> - <listitem><simpara>LENGTH</simpara></listitem> - <listitem><simpara>SCALE</simpara></listitem> - <listitem><simpara>RADIX</simpara></listitem> - <listitem><simpara>NULLABLE</simpara></listitem> - <listitem><simpara>REMARKS</simpara></listitem> - </itemizedlist> - </para> - <simpara> - I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, - TABLE_OWNER e TABLE_NAME. - </simpara> - <para> - Gli argomenti <parameter>proprietario</parameter>, - <parameter>nome_tabella</parameter> e - <parameter>nome_colonna</parameter> accettano dei - criteri di ricerca ('%' per indicare zero o più - caratteri e '_' per indicare un singolo carattere). - </para> - <simpara> - Vedere anche <function>odbc_columnprivileges</function> per ottenere - i privilegi associati alle colonne. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-columnprivileges"> - <refnamediv> - <refname>odbc_columnprivileges</refname> - <refpurpose> - Restituisce un identificatore di risultato che permette di ricavare l'elenco - delle colonne e dei privilegi ad esse associati. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_columnprivileges</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> - <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> - <paramdef>string <parameter><optional>nome_tabella</optional></parameter></paramdef> - <paramdef>string <parameter><optional>nome_colonna</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Elenca le colonne e i privilegi associati ad esse per la tabella data. - La funzione ritorna un identificatore di risultato ODBC - oppure <literal>falso</literal> se si verifica un errore. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>TABLE_OWNER</simpara></listitem> - <listitem><simpara>TABLE_NAME</simpara></listitem> - <listitem><simpara>GRANTOR</simpara></listitem> - <listitem><simpara>GRANTEE</simpara></listitem> - <listitem><simpara>PRIVILEGE</simpara></listitem> - <listitem><simpara>IS_GRANTABLE</simpara></listitem> - </itemizedlist> - </para> - <simpara> - I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, - TABLE_OWNER e TABLE_NAME. - </simpara> - <para> - L'argomento <parameter>nome_colonna</parameter> accetta dei - criteri di ricerca ('%' per indicare zero o più - caratteri e '_' per indicare un singolo carattere). - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-gettypeinfo"> - <refnamediv> - <refname>odbc_gettypeinfo</refname> - <refpurpose> - Restituisce un identificatore di risultato contenente informazioni - sui tipi di dati supportati dalla sorgente di dati. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_gettypeinfo</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>int <parameter><optional>tipo_dato</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Recupera informazioni sui tipi di dati supportati dalla - sorgente di dati. La funzione restituisce un identificatore - di risultato ODBC oppure <literal>falso</literal> su errore. - L'argomento opzionale <parameter>tipo_dato</parameter> può essere - utilizzato per restringere l'informazione su un singolo tipo. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>TYPE_NAME</simpara></listitem> - <listitem><simpara>DATA_TYPE</simpara></listitem> - <listitem><simpara>PRECISION</simpara></listitem> - <listitem><simpara>LITERAL_PREFIX</simpara></listitem> - <listitem><simpara>LITERAL_SUFFIX</simpara></listitem> - <listitem><simpara>CREATE_PARAMS</simpara></listitem> - <listitem><simpara>NULLABLE</simpara></listitem> - <listitem><simpara>CASE_SENSITIVE</simpara></listitem> - <listitem><simpara>SEARCHABLE</simpara></listitem> - <listitem><simpara>UNSIGNED_ATTRIBUTE</simpara></listitem> - <listitem><simpara>MONEY</simpara></listitem> - <listitem><simpara>AUTO_INCREMENT</simpara></listitem> - <listitem><simpara>LOCAL_TYPE_NAME</simpara></listitem> - <listitem><simpara>MINIMUM_SCALE</simpara></listitem> - <listitem><simpara>MAXIMUM_SCALE</simpara></listitem> - </itemizedlist> - </para> - <simpara>I campi di ordinamento delle righe risultanti sono DATA_TYPE e TYPE_NAME. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-primarykeys"> - <refnamediv> - <refname>odbc_primarykeys</refname> - <refpurpose> - Restituisce un identificatore di risultato che può essere utilizzato - per ricavare il nome della colonna che contiene la chiave primaria - della tabella. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_primarykeys</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter>qualifica</parameter></paramdef> - <paramdef>string <parameter>proprietario</parameter></paramdef> - <paramdef>string <parameter>tabella</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Restituisce il nome della colonna che contiene la chiave primaria - per la tabella. La funzione ritorna un identificatore di risultato - ODBC oppure <literal>falso</literal> se si verifica un errore. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>TABLE_OWNER</simpara></listitem> - <listitem><simpara>TABLE_NAME</simpara></listitem> - <listitem><simpara>COLUMN_NAME</simpara></listitem> - <listitem><simpara>KEY_SEQ</simpara></listitem> - <listitem><simpara>PK_NAME</simpara></listitem> - </itemizedlist> - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-foreignkeys"> - <refnamediv> - <refname>odbc_foreignkeys</refname> - <refpurpose> - Restituisce l'elenco delle chiavi esterne per la tabella indicata, - oppure la lista delle chiavi esterne in altre tabelle che fanno - riferimento alla chiave primaria della tabella indicata. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_foreignkeys</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter>pk_qualifica</parameter></paramdef> - <paramdef>string <parameter>pk_proprietario</parameter></paramdef> - <paramdef>string <parameter>pk_tabella</parameter></paramdef> - <paramdef>string <parameter>fk_qualifica</parameter></paramdef> - <paramdef>string <parameter>fk_proprietario</parameter></paramdef> - <paramdef>string <parameter>fk_tabella</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione <function>odbc_foreignkeys</function> ritorna informazioni sulle - chiavi esterne. Restituisce un identificatore di risultato oppure - <literal>falso</literal> se si verifica un errore. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>PKTABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>PKTABLE_OWNER</simpara></listitem> - <listitem><simpara>PKTABLE_NAME</simpara></listitem> - <listitem><simpara>PKCOLUMN_NAME</simpara></listitem> - <listitem><simpara>FKTABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>FKTABLE_OWNER</simpara></listitem> - <listitem><simpara>FKTABLE_NAME</simpara></listitem> - <listitem><simpara>FKCOLUMN_NAME</simpara></listitem> - <listitem><simpara>KEY_SEQ</simpara></listitem> - <listitem><simpara>UPDATE_RULE</simpara></listitem> - <listitem><simpara>DELETE_RULE</simpara></listitem> - <listitem><simpara>FK_NAME</simpara></listitem> - <listitem><simpara>PK_NAME</simpara></listitem> - </itemizedlist> - </para> - <simpara> - Se l'argomento <parameter>pk_tabella</parameter> contiene il nome di una tabella, - la funzione <function>odbc_foreignkeys</function> ritorna una serie di righe - contenenti i dati della chiave primaria della tabella e di tutte le chiavi esterne - che hanno riferimenti a questa. - </simpara> - <simpara> - Se l'argomento <parameter>fk_tabella</parameter> contiene il nome di una tabella, - la funzione <function>odbc_foreignkeys</function> ritorna una serie di righe - contenenti i dati delle chiavi esterne della tabella e delle chiavi primarie - ( di altre tabelle ) a cui queste hanno riferimenti. - </simpara> - <simpara> - Se entrambi gli argomenti <parameter>pk_tabella</parameter> e - <parameter>fk_tabella</parameter> contengono nomi di tabelle, - <function>odbc_foreignkeys</function> restituisce le chiavi esterne - della tabella specificata in <parameter>fk_tabella</parameter> che hanno - riferimenti alla chiave primaria della tabella indicata in - <parameter>pk_tabella</parameter>. La funzione dovrebbe trovare almeno una chiave. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-procedures"> - <refnamediv> - <refname>odbc_procedures</refname> - <refpurpose> - Restituisce l'elenco delle procedure memorizzate in una specifica - sorgente di dati. La funzione ritorna un identificatore di risultato che - punta alle informazioni reperite. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_procedures</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> - <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> - <paramdef>string <parameter><optional>nome</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Si ottiene l'elenco di tutte le procedure presenti nei limiti richiesti. - La funzione restituisce un identificatore di risultato, - oppure &false; su errore. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>PROCEDURE_QUALIFIER</simpara></listitem> - <listitem><simpara>PROCEDURE_OWNER</simpara></listitem> - <listitem><simpara>PROCEDURE_NAME</simpara></listitem> - <listitem><simpara>NUM_INPUT_PARAMS</simpara></listitem> - <listitem><simpara>NUM_OUTPUT_PARAMS</simpara></listitem> - <listitem><simpara>NUM_RESULT_SETS</simpara></listitem> - <listitem><simpara>REMARKS</simpara></listitem> - <listitem><simpara>PROCEDURE_TYPE</simpara></listitem> - </itemizedlist> - </para> - <para> - Gli argomenti <parameter>proprietario</parameter> e <parameter>nome</parameter> - accettano dei criteri di ricerca ('%' per indicare zero o più - caratteri e '_' per indicare un singolo carattere). - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-procedurecolumns"> - <refnamediv> - <refname>odbc_procedurecolumns</refname> - <refpurpose> - Recupera informazioni sui parametri delle procedure. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_procedurecolumns</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> - <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> - <paramdef>string <parameter><optional>procedura</optional></parameter></paramdef> - <paramdef>string <parameter><optional>colonna</optional></parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - La funzione ritorna la lista dei parametri di input e di output e anche - delle colonne che concorrono al determinazione del risultato per le procedure - indicate. Viene restituito un identificatore di risultato oppure - &false; se si è un errore. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>PROCEDURE_QUALIFIER</simpara></listitem> - <listitem><simpara>PROCEDURE_OWNER</simpara></listitem> - <listitem><simpara>PROCEDURE_NAME</simpara></listitem> - <listitem><simpara>COLUMN_NAME</simpara></listitem> - <listitem><simpara>COLUMN_TYPE</simpara></listitem> - <listitem><simpara>DATA_TYPE</simpara></listitem> - <listitem><simpara>TYPE_NAME</simpara></listitem> - <listitem><simpara>PRECISION</simpara></listitem> - <listitem><simpara>LENGTH</simpara></listitem> - <listitem><simpara>SCALE</simpara></listitem> - <listitem><simpara>RADIX</simpara></listitem> - <listitem><simpara>NULLABLE</simpara></listitem> - <listitem><simpara>REMARKS</simpara></listitem> - </itemizedlist> - </para> - <simpara>I campi di ordinamento delle righe risultanti sono PROCEDURE_QUALIFIER, PROCEDURE_OWNER, - PROCEDURE_NAME e COLUMN_TYPE. - </simpara> - <para> - Gli argomenti <parameter>proprietario</parameter>, <parameter>procedura</parameter> - e <parameter>colonna</parameter> accettano dei - criteri di ricerca ('%' per indicare zero o più - caratteri e '_' per indicare un singolo carattere). - </para> - </refsect1> - </refentry> - - <refentry id="function.odbc-specialcolumns"> - <refnamediv> - <refname>odbc_specialcolumns</refname> - <refpurpose> - Restituisce sia il set di colonne che identificano in modo univoco - una riga nella tabella, sia colonne che sono automaticamente - aggiornate quando un qualsiasi campo della riga viene aggiornato - da una transazione. - </refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_specialcolumns</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>int <parameter>tipo</parameter></paramdef> - <paramdef>string <parameter>qualifica</parameter></paramdef> - <paramdef>string <parameter>proprietario</parameter></paramdef> - <paramdef>string <parameter>tabella</parameter></paramdef> - <paramdef>int <parameter>visibilità</parameter></paramdef> - <paramdef>int <parameter>nullable</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Quando l'argomento tipo è impostato a SQL_BEST_ROWID, - <function>odbc_specialcolumns</function> restituisce la colonna - o le colonne che identificano in modo univoco ciascuna riga nella tabella. - </simpara> - <simpara> - Quando l'argomento tipo è impostato a SQL_ROWVER, - <function>odbc_specialcolumns</function> restituisce la colonna - o il set di colonne ottimali, attraverso cui, ottenendo i valori - da dette colonne, è possibile identificare in modo univoco ciascun record - della tabella indicata. - </simpara> - <simpara> - La funzione restituisce un identificatore di risultato ODBC, - oppure <literal>falso</literal> su errore. - </simpara> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>SCOPE</simpara></listitem> - <listitem><simpara>COLUMN_NAME</simpara></listitem> - <listitem><simpara>DATA_TYPE</simpara></listitem> - <listitem><simpara>TYPE_NAME</simpara></listitem> - <listitem><simpara>PRECISION</simpara></listitem> - <listitem><simpara>LENGTH</simpara></listitem> - <listitem><simpara>SCALE</simpara></listitem> - <listitem><simpara>PSEUDO_COLUMN</simpara></listitem> - </itemizedlist> - </para> - <simpara> - Le righe del risultato sono ordinate in base alla colonna SCOPE. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.odbc-statistics"> - <refnamediv> - <refname>odbc_statistics</refname> - <refpurpose>Recupera informazioni statistiche sulla tabella</refpurpose> - </refnamediv> - <refsect1> - <title>Descrizione</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>odbc_statistics</function></funcdef> - <paramdef>int <parameter>id_connessione</parameter></paramdef> - <paramdef>string <parameter>qualifica</parameter></paramdef> - <paramdef>string <parameter>proprietario</parameter></paramdef> - <paramdef>string <parameter>nome_tabella</parameter></paramdef> - <paramdef>int <parameter>unico</parameter></paramdef> - <paramdef>int <parameter>precisione</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Si ottengono informazioni statistiche sulla tabella e i propri indici. - La funzione restituisce un identificatore di risultato ODBC, - oppure <literal>falso</literal> su errore. - </para> - <para> - Le righe risultanti dall'elaborazione contengono i seguenti campi: - <itemizedlist> - <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> - <listitem><simpara>TABLE_OWNER</simpara></listitem> - <listitem><simpara>TABLE_NAME</simpara></listitem> - <listitem><simpara>NON_UNIQUE</simpara></listitem> - <listitem><simpara>INDEX_QUALIFIER</simpara></listitem> - <listitem><simpara>INDEX_NAME</simpara></listitem> - <listitem><simpara>TYPE</simpara></listitem> - <listitem><simpara>SEQ_IN_INDEX</simpara></listitem> - <listitem><simpara>COLUMN_NAME</simpara></listitem> - <listitem><simpara>COLLATION</simpara></listitem> - <listitem><simpara>CARDINALITY</simpara></listitem> - <listitem><simpara>PAGES</simpara></listitem> - <listitem><simpara>FILTER_CONDITION</simpara></listitem> - </itemizedlist> - </para> - <simpara> - I campi di ordinamento delle righe risultanti sono NON_UNIQUE, TYPE, INDEX_QUALIFIER, - INDEX_NAME e SEQ_IN_INDEX. - </simpara> - </refsect1> - </refentry> - - </reference> - -<!-- Mantenere questo commento alla fine del file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> - + <reference id="ref.odbc"> + <title>Funzioni ODBC Unificate</title> + <titleabbrev>ODBC</titleabbrev> + <partintro> + <simpara> + In aggiunta al normale supporto ODBC, le funzioni ODBC unificate del + PHP consentono l'accesso a diversi database che hanno preso in prestito + la semantica dell'API ODBC per implementare la loro API. Invece di mantenere + più driver per database che sono tutti pressoché identici, questi driver sono + stati riuniti in un singolo insieme di funzioni ODBC. + </simpara> + <simpara> + I seguenti database sono supportati dalle funzioni ODBC unificate: + <ulink url="&url.adabas;">Adabas D</ulink>, <ulink + url="&url.ibmdb2;">IBM DB2</ulink>, <ulink + url="&url.iodbc;">iODBC</ulink>, <ulink + url="&url.solid;">Solid</ulink>, and <ulink + url="&url.sybase;">Sybase SQL Anywhere</ulink>. + </simpara> +<!-- install.xml has changed, so this link is no longer working + <simpara> + Please see the <link + linkend="database-support-options">Installation on Unix + Systems</link> chapter for more information about configuring PHP + with these databases. + </simpara> +--> + <note> + <simpara> + Nella connessione ai database sopra elencati non vengono coinvolte funzioni + ODBC. Le funzioni che vengono utilizzate per collegarsi nativamente con essi + condividono solamente lo stesso nome e sintassi delle funzioni ODBC. + </simpara> + </note> + </partintro> + + <refentry id="function.odbc-autocommit"> + <refnamediv> + <refname>odbc_autocommit</refname> + <refpurpose>Setta il parametro autocommit</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_autocommit</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>int <parameter><optional>OnOff</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Se non viene fornito il parametro <parameter>OnOff</parameter>, la funzione + restituisce lo stato dell'auto-commit per + <parameter>id_connessione</parameter>. Il valore reso è vero se l'autocommit + è attivo, altrimenti falso se non è attivato oppure si verifica un errore. + </para> + <para> + Se il campo <parameter>OnOff</parameter> è posto a vero, l' auto-commit è abilitato, + se è valorizzato a falso l'autocommit è disabilitato. La funzione restituisce + <literal>vero</literal> se l'operazione riesce, <literal>falso</literal> se si + verifica un errore. + </para> + <para> + Per default, l'autocommit è abilitato. La disabilitazione + dell'autocommit equivale ad iniziare una transazione. + </para> + <simpara> + Vedere inoltre + <function>odbc_commit</function> e + <function>odbc_rollback</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-binmode"> + <refnamediv> + <refname>odbc_binmode</refname> + <refpurpose>Gestione delle colonne di dati binari</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_binmode</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>modalità</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + (Tipi di campi ODBC SQL coinvolti: BINARY, VARBINARY, LONGVARBINARY) + </para> + <itemizedlist> + <listitem> + <simpara> + ODBC_BINMODE_PASSTHRU: Restituzione del dato binario direttamente al client + </simpara> + </listitem> + <listitem> + <simpara> + ODBC_BINMODE_RETURN: restituisce il dato inalterato + </simpara> + </listitem> + <listitem> + <simpara> + ODBC_BINMODE_CONVERT: Conversione in char + </simpara> + </listitem> + </itemizedlist> + <para> + Quando si esegue la conversione da dati binari SQL a dati di tipo char del C, + ciascun byte ( 8 bits) dei dati sorgenti vengono rappresentati da 2 caratteri ASCII. + Questi caratteri sono la rappresentazione ASCII dei numeri nella + loro forma esadecimale. Ad esempio, il valore binario 00000001 è + convertito in <literal>"01"</literal> e il valore binario 11111111 è + convertito come <literal>"FF"</literal>. + <table> + <title>Gestione del tipo LONGVARBINARY </title> + <tgroup cols="3"> + <thead> + <row> + <entry>Modalità</entry> + <entry>impostazione di longreadlen</entry> + <entry>Comportamento</entry> + </row> + </thead> + <tbody> + <row> + <entry>ODBC_BINMODE_PASSTHRU</entry> + <entry>0</entry> + <entry>direttamente al client</entry> + </row> + <row> + <entry>ODBC_BINMODE_RETURN</entry> + <entry>0</entry> + <entry>direttamente al client</entry> + </row> + <row> + <entry>ODBC_BINMODE_CONVERT</entry> + <entry>0</entry> + <entry>direttamente al client</entry> + </row> + <row> + <entry>ODBC_BINMODE_PASSTHRU</entry> + <entry>>0</entry> + <entry>direttamente al client</entry> + </row> + <row> + <entry>ODBC_BINMODE_RETURN</entry> + <entry>>0</entry> + <entry>ritorna inalterato</entry> + </row> + <row> + <entry>ODBC_BINMODE_CONVERT</entry> + <entry>>0</entry> + <entry>ritorna come char</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + Se viene utilizzata la funzione <function>odbc_fetch_into</function>, nei casi + in cui il dato viene inviato direttamente al client, quest'ultima + restituisce una stringa vuota per le colonne binarie. + </para> + <para> + Se l'argomento <parameter>id_risultato</parameter> è valorizzato a <literal>0</literal>, + il settaggio viene applicato come default per i nuovi risultati. + <note> + <simpara> + I valori di default per longreadlen è <literal>4096</literal>, mentre la modalità di + default è <literal>ODBC_BINMODE_RETURN</literal>. La gestione delle colonne + di campi long binary, è anche gestita dalla funzione + <function>odbc_longreadlen</function> + </simpara> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-close"> + <refnamediv> + <refname>odbc_close</refname> + <refpurpose>Chiude una connessione ODBC</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>odbc_close</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>odbc_close</function> chiude la connessione + con il database server associata all'identificativo di connessione + indicato. + <note> + <simpara> + Se ci sono delle transazioni aperte sulla connessione richiesta, la funzione + fallisce. In questo caso la connessione resta aperta. + </simpara> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-close-all"> + <refnamediv> + <refname>odbc_close_all</refname> + <refpurpose>Chiude tutte le connessioni ODBC</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>odbc_close_all</function></funcdef> + <void/> + </funcprototype> + </funcsynopsis> + <para> + <function>odbc_close_all</function>chiude tutte le connessioni + aperte con il database server + <note> + <simpara> + Se ci sono delle transazioni aperte sulla connessione richiesta, la funzione + fallisce. In questo caso la connessione resta aperta. + </simpara> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-commit"> + <refnamediv> + <refname>odbc_commit</refname> + <refpurpose>Esegue una transazione ODBC</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_commit</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce: <literal>vero</literal> per operazione corretta, + <literal>falso</literal> se si verifica un errore. Sono eseguite tutte le + transazioni pendenti sulla connessione indicata dall'argomento <parameter>id_connessione</parameter>. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-connect"> + <refnamediv> + <refname>odbc_connect</refname> + <refpurpose>Apre una connessione con una fonte di dati</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_connect</function></funcdef> + <paramdef>string <parameter>dsn</parameter></paramdef> + <paramdef>string <parameter>utente</parameter></paramdef> + <paramdef>string <parameter>password</parameter></paramdef> + <paramdef>int <parameter><optional>tipo_cursore</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce un identificatore di connessione ODBC oppure 0 (<literal>falso</literal>) + se si verifica un errore. + </para> + <simpara> + L'identificatore di connessione ritornato da questa funzione è + utilizzato dalle altre funzioni ODBC. Si possono avere più connessioni + aperte contemporaneamente. Il quarto parametro ( opzionale ), setta + il tipo di cursore da utilizzare per questa connessione. Normalmente + questo parametro non è necessario, ma può essere utilizzato per aggirare + dei problemi che si manifestano con alcuni driver ODBC. + </simpara> + <simpara> + Con alcuni driver ODBC, l'esecuzione di complesse procedure può + generare un errore tipo: "Non si riesce ad aprire un cursore sulla + procedura che richieda qualsiasi cosa oltre ad un singola istruzione + select". L'uso di SQL_CUR_USE_ODBC, può evitare questo errore. Inoltre + alcuni driver non supportano il parametro row_number della funzione + <function>odbc_fetch_row</function>. In questo caso SQL_CUR_USE_ODBC + può essere d'aiuto. + </simpara> + <simpara> + Il campo tipo_cursore può assumere le seguenti costanti: + </simpara> + <para> + <itemizedlist> + <listitem> + <simpara> + SQL_CUR_USE_IF_NEEDED + </simpara> + </listitem> + <listitem> + <simpara> + SQL_CUR_USE_ODBC + </simpara> + </listitem> + <listitem> + <simpara> + SQL_CUR_USE_DRIVER + </simpara> + </listitem> + <listitem> + <simpara> + SQL_CUR_DEFAULT + </simpara></listitem> + </itemizedlist> + </para> + <simpara> + Per le connessioni persistenti vedere + <function>odbc_pconnect</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-cursor"> + <refnamediv> + <refname>odbc_cursor</refname> + <refpurpose>Restituisce il nome del cursore</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>odbc_cursor</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + odbc_cursor restituisce il nome del cursore per l'argomento id_risultato. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-do"> + <refnamediv> + <refname>odbc_do</refname> + <refpurpose>Sinonimo di <function>odbc_exec</function></refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_do</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter>query</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>odbc_do</function> esegue una query sulla connessione + data. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-exec"> + <refnamediv> + <refname>odbc_exec</refname> + <refpurpose>Prepara ed esegue una espressione SQL</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_exec</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter>testo_query</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce <literal>falso</literal> se si verifica un errore. Restituisce + un identificatore del risultato se l'espressione SQL viene + eseguita correttamente. + </para> + <para> + <function>odbc_exec</function> invia una espressione SQL + al server tramite la connessione specificata da + <parameter>id_connessione</parameter>. Questo parametro deve essere + un identificativo valido restituito da + <function>odbc_connect</function> oppure + <function>odbc_pconnect</function>. + </para> + <simpara> + Vedere anche: <function>odbc_prepare</function> ed + <function>odbc_execute</function> per l'esecuzione di molteplici + espressioni SQL. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-execute"> + <refnamediv> + <refname>odbc_execute</refname> + <refpurpose>Esecuzione di un'espressione memorizzata</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_execute</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>array + <parameter><optional>array_parametri</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esegue una espressione SQL memorizzata tramite la funzione + <function>odbc_prepare</function>. Restituisce + <literal>vero</literal> se l'esecuzione riesce, + <literal>falso</literal> in caso negativo. L'array + <parameter>array_parametri</parameter> occorre soltanto + se è necessario fornire parametri all'espressione. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-fetch-into"> + <refnamediv> + <refname>odbc_fetch_into</refname> + <refpurpose>Scarica una riga del risultato della query in un array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_fetch_into</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter><optional>numero_riga</optional></parameter></paramdef> + <paramdef>array <parameter>array_dati</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione restituisce il numero di colonne presenti nel risultato; + <literal>falso</literal> se si verifica un errore. + Il parametro <parameter>array_dati</parameter> deve essere passato per referenza, + ma può essere di qualsiasi tipo dato che verrà convertito + in array. Nell'array saranno posti i valori delle colonne di una riga tratta dalla tabella + risultante dalla query a partire dall'indice 0. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-fetch-row"> + <refnamediv> + <refname>odbc_fetch_row</refname> + <refpurpose>Estrae una riga</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_fetch_row</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter><optional>numero_riga</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Se <function>odbc_fetch_row</function> ha successo ( c'è almeno + una riga), la funzione restituisce <literal>vero</literal>. Altrimenti, se non vi sono più + righe, la funzione restituisce <literal>falso</literal>. + </para> + <para> + <function>odbc_fetch_row</function> estrae un record dai dati + restituiti dalle funzioni <function>odbc_do</function> / + <function>odbc_exec</function>. Dopo l'esecuzione di + <function>odbc_fetch_row</function>, i campi della riga sono + accessibili tramite la funzione <function>odbc_result</function>. + </para> + <para> + Se non viene specificato il parametro <parameter>numero_riga</parameter>, + <function>odbc_fetch_row</function> restituisce la riga successiva dal set + delle righe risultanti dalla query. Si può intercalare esecuzioni + successive di <function>odbc_fetch_row</function> con e senza il parametro + <parameter>numero_riga</parameter>. + </para> + <para> + Per spostarsi attraverso le righe risultanti, si può eseguire + <function>odbc_fetch_row</function> con il parametro + <parameter>numero_riga</parameter> impostato a 1, e quindi continuare + ad utilizzare <function>odbc_fetch_row</function> senza + <parameter>numero_riga</parameter>. Se il driver non supporta + l'estrazione di una riga per numero, il campo + <parameter>numero_riga</parameter> sarà ignorato. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-field-name"> + <refnamediv> + <refname>odbc_field_name</refname> + <refpurpose>Restituisce il nome della colonna</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>odbc_field_name</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>numero_campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione <function>odbc_field_name</function> restituisce il nome + del campo presente nella colonna richiesta all'interno di un risultato ODBC + identificato dal'argomento id_risultato. La numerazione delle colonne parte da 1. + La funzione restituisce <literal>falso</literal> se si verifica un errore. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-field-num"> + <refnamediv> + <refname>odbc_field_num</refname> + <refpurpose>Restituisce il numero di colonna</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_field_num</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>string <parameter>nome_campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>odbc_field_num</function> restituisce il numero della colonna + in cui si trova il campo richiesto all'interno di un risultato ODBC indicato + dall'argomento id_risultato. La numerazione delle colonne + parte da 1. + Si ottiene <literal>falso</literal> se si verifica un errore. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-field-type"> + <refnamediv> + <refname>odbc_field_type</refname> + <refpurpose>Tipo di campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>odbc_field_type</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>numero_campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione <function>odbc_field_type</function> restituisce il tipo + di dato SQL del campo indicato dal numero all'interno di un set di righe + referenziate dall'identificativo di risultato ODBC passato. + La numerazione delle colonne parte da 1. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-field-len"> + <refnamediv> + <refname>odbc_field_len</refname> + <refpurpose>Restituisce la dimensione (precisione) di un campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_field_len</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>numero_campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + All'interno di un set di righe, referenziate dall'identificativo + di risultato ODBC fornito, la funzione <function>odbc_field_len</function> + restituisce la dimensione ( precisione ) del campo indicato dall'argomento + <parameter>numero_campo</parameter>. La numerazione dei campi parte da 1. + </para> + <simpara> + Vedere anche: <function>odbc_field_scale</function> per ottenere la scala di + un numero in virgola mobile. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-field-precision"> + <refnamediv> + <refname>odbc_field_precision</refname> + <refpurpose>Sinonimo di <function>odbc_field_len</function></refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>odbc_field_precision</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>numero_campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + All'interno di un set di righe, referenziate dall'identificativo + di risultato ODBC fornito, la funzione <function>odbc_field_precision</function> + restituisce la precisione del campo indicato dal numero di campo indicato. + </para> + <para> + Vedere anche: <function>odbc_field_scale</function> per ottenere la scala di + un numero in virgola mobile. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-field-scale"> + <refnamediv> + <refname>odbc_field_scale</refname> + <refpurpose>Restituisce la scala di un campo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>odbc_field_scale</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>int <parameter>numero_campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + All'interno di un set di righe, referenziate dall'identificativo + di risultato ODBC fornito, la funzione <function>odbc_field_precision</function> + restituisce la scala del campo indicato dal numero di campo indicato. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-free-result"> + <refnamediv> + <refname>odbc_free_result</refname> + <refpurpose>Libera le risorse associate ad un risultato</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_free_result</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce sempre <literal>vero</literal>. + </para> + <para> + La funzione <function>odbc_free_result</function> permette + di non utilizzare molta memoria durante l'esecuzione di uno script. + Infatti, se si è sicuri di non avere più bisogno dei dati del risultato, + si può eseguire <function>odbc_free_result</function>, e la memoria associata + a <parameter>id_risultato</parameter> sarà liberata. Se la funzione + non viene utilizzata, le aree di memoria resteranno disponibili per tutta + la durata dello script. Al termine verranno liberate in modo automatico. + </para> + <para> + <note> + <simpara> + Se si ha l'autocommit disabilitato (vedere + <function>odbc_autocommit</function>) e si esegue + <function>odbc_free_result</function> prima di eseguire il commit, tutte le + transazioni pendenti saranno annullate, + </simpara> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-longreadlen"> + <refnamediv> + <refname>odbc_longreadlen</refname> + <refpurpose>Gestione di colonne LONG</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_longreadlen</function></funcdef> + <paramdef>int <parameter>id_risultato </parameter></paramdef> + <paramdef>int <parameter>lunghezza</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + (tipi di campi ODBC ed SQL coinvolti: LONG, LONGVARBINARY) Tramite + l'argomento lunghezza si controlla il numero di byte da ritornare a PHP. + Se il campo viene posto a 0, i dati della colonna saranno passati + direttamente al client. + </para> + <note> + <simpara> + Per la gestione delle colonne di tipo LONGVARBINARY si utilizza anche + <function>odbc_binmode</function>. + </simpara> + </note> + </refsect1> + </refentry> + + <refentry id="function.odbc-num-fields"> + <refnamediv> + <refname>odbc_num_fields</refname> + <refpurpose>Numero di colonne in un esito</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_num_fields</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + All'interno di un set di righe, referenziate dall'identificativo + di risultato ODBC fornito, la funzione <function>odbc_num_fields</function> + restituisce il numero di campi (colonne) presenti. La funzione restituisce -1 se vi + è un errore. L'argomento fornito è un identificatore di esito restituito + dalla funzione <function>odbc_exec</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-pconnect"> + <refnamediv> + <refname>odbc_pconnect</refname> + <refpurpose>Apre una connessione persistente verso un database</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_pconnect</function></funcdef> + <paramdef>string <parameter>dsn</parameter></paramdef> + <paramdef>string <parameter>utente</parameter></paramdef> + <paramdef>string <parameter>password</parameter></paramdef> + <paramdef>int <parameter><optional>tipo_cursore</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce un identificatore di connessione ODBC oppure 0 (<literal>falso</literal>) + su errore. Questa funzione è molto simile a <function>odbc_connect</function>, + eccetto che la connessione non viene realmente chiusa quando + lo script finisce. Future richieste di connessione che utilizzino la + stessa combinazione di <parameter>dsn</parameter>, + <parameter>utente</parameter>, <parameter>password</parameter> + (eseguite sia utilizzando <function>odbc_connect</function>, sia utilizzando + <function>odbc_pconnect</function>) possono riutilizzare la connessione. + </para> + <para> + <note> + <simpara> + Le connessioni persistenti non hanno effetti se PHP viene utilizzato + come programma CGI. + </simpara> + </note> + </para> + <para> + Per informazioni sul campo opzionale tipo_cursore, vedere la funzione + <function>odbc_connect</function>. Per maggiori dettagli sulle + connessioni persistenti, fare riferimento alla FAQ di PHP. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-prepare"> + <refnamediv> + <refname>odbc_prepare</refname> + <refpurpose>Predispone un'espressione all'esecuzione</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_prepare</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter>testo_query</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione ritorna <literal>falso</literal> su errore. + </para> + <para> + Restituisce un identificativo di risultato ODBC se l'espressione SQL + viene predisposta correttamente. L'identificativo restituito può essere + utilizzato successivamente per eseguire l'espressione utilizzando + la funzione <function>odbc_execute</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-num-rows"> + <refnamediv> + <refname>odbc_num_rows</refname> + <refpurpose>Numero di righe in un risultato</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_num_rows</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>odbc_num_rows</function> ritorna il numero di record + presenti in un risultato ODBC. La funzione ritorna -1 se si verifica un errore. + Per le clausole INSERT, UPDATE e DELETE, + <function>odbc_num_rows</function> ritorna il numero di righe + coinvolte. Nella clausola SELECT questo <literal>può</literal> essere + il numero di righe disponibili. + </para> + <para> + Nota: Con diversi driver, la funzione <function>odbc_num_rows</function>, utilizzata con + lo scopo di determinare il numero di righe dopo una SELECT, restituisce -1. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-result"> + <refnamediv> + <refname>odbc_result</refname> + <refpurpose>Restituisce il contenuto dei campi</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>odbc_result</function></funcdef> + <paramdef>int <parameter>id_risultato</parameter></paramdef> + <paramdef>mixed <parameter>campo</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce il contenuto dei campi. + </para> + <para> + Il parametro <parameter>campo</parameter> può essere sia un intero + indicante il numero di colonna del campo desiderato; sia una stringa + contenente il nome del campo. Ad esempio: + <informalexample><programlisting> +$item_3 = odbc_result ($Query_ID, 3); +$item_val = odbc_result ($Query_ID, "val"); + </programlisting> + </informalexample> + </para> + <para> + Nel primo caso l'esecuzione di <function>odbc_result</function> + restituisce il terzo campo del record corrente. + Nel secondo, la funzione <function>odbc_result</function> restituisce il valore + del campo il cui nome è "val", sempre utilizzando i dati dal record corrente. + Si ha un errore qualora il numero di colonna fornito sia minore di 1 + oppure sia superiore al numero delle colonne ( o campi ) presenti + nel record corrente. Analogamente, si ottiene un errore se il nome del campo + richiesto non sia presente nella tabella/e oggetto della ricerca. + </para> + <para> + L'indice dei campi parte da 1. Per quanto riguarda la gestione dei campi + di tipo binario o long fare riferimento a <function>odbc_binmode + </function> e a <function>odbc_longreadlen</function>. + +<!-- + +Se il campo richiesto contiene dati binari o + è un campo di tipo LONG, più lungo di 4096 bytes, + il contenuto non viene restituito, ma invece viene + inviato direttamente al client. + Se si ha necessità di avere restituiti i dati binari, utilizzare + la funzione SQL HEX(), in modo da ottenere i dati del campo in + notazione esadecimale. Ad esempio: "SELECT + HEX(binary_col) FROM mytable" +--> + + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-result-all"> + <refnamediv> + <refname>odbc_result_all</refname> + <refpurpose>Visualizza il risultato in una tabella HTML</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_result_all</function></funcdef> + <paramdef>int <parameter>id_esito</parameter></paramdef> + <paramdef>string <parameter><optional>formato</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce il numero di righe elaborate, oppure + <literal>falso</literal> se si verifica un errore. + </para> + <para> + Dato un identificatore di risultato restituito da <function>odbc_exec</function>, + la funzione <function>odbc_result_all</function> visualizza tutti i record + ottenuti in una di tabella in formato HTML. + Utilizzando il parametro opzionale <parameter>formato</parameter>, è possibile + fornire informazioni addizionali sulla formattazione della tabella. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-rollback"> + <refnamediv> + <refname>odbc_rollback</refname> + <refpurpose>Annulla una transazione</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_rollback</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Annulla tutte le operazioni pendenti sulla connessione indicata + da <parameter>id_connessione</parameter>. Se ha successo ritorna + <literal>vero</literal>, altrimenti <literal>falso</literal>. + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-setoption"> + <refnamediv> + <refname>odbc_setoption</refname> + <refpurpose> + Settaggio dei parametri ODBC. Restituisce falso se si verifica un errore, altrimenti vero. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_setoption</function></funcdef> + <paramdef>int <parameter>identificativo</parameter></paramdef> + <paramdef>int <parameter>funzione</parameter></paramdef> + <paramdef>int <parameter>opzione</parameter></paramdef> + <paramdef>int <parameter>parametro</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Questa funzione permette di manipolare i parametri ODBC per + la connessione o il risultato di una query indicati. La funzione è stata + sviluppata per permettere di aggirare dei problemi emersi in alcuni + driver ODBC. Pertanto si dovrebbe utilizzare questa funzione soltanto se si è + dei programmatori e si conoscono gli effetti generati dalle varie + opzioni. Dato che ogni singola versione di driver ODBC supporta differenti + parametri, occorre avere a disposizione un buon manuale del + driver per avere esposti tutti i differenti settaggi che possono + essere utilizzati. + </para> + <para> + Poiché i parametri possono variare in base al driver ODBC, è fortemente sconsigliato + l'uso di questa funzione in script resi pubblici. Inoltre, + alcune opzioni di ODBC non sono gestibili da questa funzione, + dato che devono essere specificate prima di stabilire la + connessione o prima della preparazione della query. + </para> + <para> + Il campo <parameter>identificativo</parameter> indica la connessione + o l'esito su cui si varia il settaggio. Per la funzione SQLSetConnectOption(), + questo indica l'identificativo di connessione, per SQLSetStmtOption(), + indica l'identificativo del risultato. + </para> + <para> + Il campo <parameter>funzione</parameter> indica quale funzione ODBC + utilizzare. Dovrebbe essere valorizzato a 1 per SQLSetConnectOption() + e a 2 per SQLSetStmtOption(). + </para> + <para> + Il parametro <parameter>opzione</parameter> indica l'opzione da settare.</para> + <para> + Il campo <parameter>parametro</parameter> indica il valore per + l'<parameter>opzione</parameter> richiesta. + <example> + <title>Esempi di utilizzo </title> + <programlisting role="php"> +// 1. Il valore 102 per il campo opzione in SQLSetConnectOption() indica SQL_AUTOCOMMIT. +// Il valore 1 per SQL_AUTOCOMMIT è SQL_AUTOCOMMIT_ON. +// Pertanto questo esempio ha il medesimo effetto di: +// odbc_autocommit($conn, true); + +odbc_setoption ($conn, 1, 102, 1); + +// 2. Il valore 0 per il campo opzione in SQLSetStmtOption() indica SQL_QUERY_TIMEOUT. +// In questo esempio si setta il timeout di una query a 30 secondi. + +$result = odbc_prepare ($conn, $sql); +odbc_setoption ($result, 2, 0, 30); +odbc_execute ($result); + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-tables"> + <refnamediv> + <refname>odbc_tables</refname> + <refpurpose> + Restituisce l'elenco delle tabelle presenti in una specifica + sorgente di dati. Restituisce l'identificatore di risultato in cui + vi sono le informazioni. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_tables</function></funcdef> + <paramdef>int <parameter>Id_connessione</parameter></paramdef> + <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> + <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> + <paramdef>string <parameter><optional>nome</optional></parameter></paramdef> + <paramdef>string <parameter><optional>tipo</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione elenca tutte le tabelle presenti nei limiti richiesti. Restituisce un identificatore + di risultato oppure <literal>falso</literal> se si verifica un errore. + </para> + <para> + Le righe risultanti hanno i seguenti campi: + <itemizedlist> + <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>TABLE_OWNER</simpara></listitem> + <listitem><simpara>TABLE_NAME</simpara></listitem> + <listitem><simpara>TABLE_TYPE</simpara></listitem> + <listitem><simpara>REMARKS</simpara></listitem> + </itemizedlist> + </para> + <simpara> + I campi di ordinamento delle righe risultanti sono TABLE_TYPE, TABLE_QUALIFIER, + TABLE_OWNER e TABLE_NAME. + </simpara> + <para> + Gli argomenti <parameter>proprietario</parameter> e <parameter>nome</parameter> + accettano dei criteri di ricerca ('%' per indicare zero o più + caratteri e '_' per indicare un singolo carattere). + </para> + <para> + Per supportare l'enumerazione delle qualifiche, dei proprietari, + e dei tipi tabelle, è stata predisposta la seguente semantica per i + campi <parameter>qualifica</parameter>, <parameter>proprietario</parameter>, + <parameter>nome</parameter>, e <parameter>tipo</parameter>: + <itemizedlist> + <listitem> + <simpara> + Se l'argomento <parameter>qualifica</parameter> è valorizzato + con il carattere percento (%) e i parametri <parameter>proprietario</parameter> + e <parameter>nome</parameter> sono delle stringhe vuote, il risultato sarà + un set di righe contenente la lista delle qualifiche previste per + la sorgente di dati. ( Tutte le colonne tranne TABLE_QUALIFIER conterranno + NULLs.) + </simpara> + </listitem> + <listitem> + <simpara> + Se l'argomento <parameter>proprietario</parameter> è valorizzato + con il carattere percento (%) e i parametri <parameter>qualifica</parameter> + e <parameter>nome</parameter> sono delle stringhe vuote, il risultato sarà + un set di righe contenente la lista dei proprietari previsti per + la sorgente di dati. ( Tutte le colonne tranne TABLE_OWNER conterranno + NULLs.) + </simpara> + </listitem> + <listitem> + <simpara> + Se l'argomento <parameter>tipo</parameter> è valorizzato + con il carattere percento (%) e i parametri <parameter>qualifica</parameter>, + <parameter>proprietario</parameter> e <parameter>nome</parameter> + sono delle stringhe vuote, il risultato sarà + un set di righe contenente la lista dei tipi di tabella previsti per + la sorgente di dati. ( Tutte le colonne tranne TABLE_TYPE conterranno + NULLs.) + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + Se l'argomento <parameter>tipo</parameter> non è una stinga vuota, deve + contenere l'elenco dei tipi interessati separati dalla virgola; + ogni singolo valore può essere, o meno, racchiuso tra apici singoli ('). + Ad esempio: "'TABLE','VIEW'" o "TABLE, VIEW" sono valori validi. + Se la sorgente di dati non supporta alcuni dei tipi di tabelle specificati, + per questi, la funzione <function>odbc_tables</function> non riporta alcuna + informazione. + </para> + <simpara> + Vedere inoltre <function>odbc_tableprivileges</function> per ottenere i + privilegi associati alla tabella. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-tableprivileges"> + <refnamediv> + <refname>odbc_tableprivileges</refname> + <refpurpose> + Elenca le tabelle ed i privilegi ad esse associati. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_tableprivileges</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> + <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> + <paramdef>string <parameter><optional>nome</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Elenca le tabelle presenti nei limiti richiesti e, per ciascuna di queste, + ne fornisce i privilegi. La funzione ritorna un identificatore di risultato ODBC, + oppure <literal>falso</literal> su errore. + </para> + <para> + Le righe risultanti dall'elaborazione hanno i seguenti campi: + <itemizedlist> + <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>TABLE_OWNER</simpara></listitem> + <listitem><simpara>TABLE_NAME</simpara></listitem> + <listitem><simpara>GRANTOR</simpara></listitem> + <listitem><simpara>GRANTEE</simpara></listitem> + <listitem><simpara>PRIVILEGE</simpara></listitem> + <listitem><simpara>IS_GRANTABLE</simpara></listitem> + </itemizedlist> + </para> + <simpara> + I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, TABLE_OWNER e + TABLE_NAME. + </simpara> + <para> + Gli argomenti <parameter>proprietario</parameter> e <parameter>nome</parameter> + accettano dei criteri di ricerca ('%' per indicare zero o più + caratteri e '_' per indicare un singolo carattere). + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-columns"> + <refnamediv> + <refname>odbc_columns</refname> + <refpurpose> + Elenca i nomi delle colonne nella tabella specificata. La funzione + ritorna un identificatore di risultato contenenti le informazioni. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_columns</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> + <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> + <paramdef>string <parameter><optional>nome_tabella</optional></parameter></paramdef> + <paramdef>string <parameter><optional>nome_colonna</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Elenca i nomi di tutte le colonne presenti nei limiti richiesti. + La funzione restituisce un identificatore di risultato + oppure &false; se si verifica un errore. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>TABLE_OWNER</simpara></listitem> + <listitem><simpara>TABLE_NAME</simpara></listitem> + <listitem><simpara>COLUMN_NAME</simpara></listitem> + <listitem><simpara>DATA_TYPE</simpara></listitem> + <listitem><simpara>TYPE_NAME</simpara></listitem> + <listitem><simpara>PRECISION</simpara></listitem> + <listitem><simpara>LENGTH</simpara></listitem> + <listitem><simpara>SCALE</simpara></listitem> + <listitem><simpara>RADIX</simpara></listitem> + <listitem><simpara>NULLABLE</simpara></listitem> + <listitem><simpara>REMARKS</simpara></listitem> + </itemizedlist> + </para> + <simpara> + I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, + TABLE_OWNER e TABLE_NAME. + </simpara> + <para> + Gli argomenti <parameter>proprietario</parameter>, + <parameter>nome_tabella</parameter> e + <parameter>nome_colonna</parameter> accettano dei + criteri di ricerca ('%' per indicare zero o più + caratteri e '_' per indicare un singolo carattere). + </para> + <simpara> + Vedere anche <function>odbc_columnprivileges</function> per ottenere + i privilegi associati alle colonne. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-columnprivileges"> + <refnamediv> + <refname>odbc_columnprivileges</refname> + <refpurpose> + Restituisce un identificatore di risultato che permette di ricavare l'elenco + delle colonne e dei privilegi ad esse associati. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_columnprivileges</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> + <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> + <paramdef>string <parameter><optional>nome_tabella</optional></parameter></paramdef> + <paramdef>string <parameter><optional>nome_colonna</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Elenca le colonne e i privilegi associati ad esse per la tabella data. + La funzione ritorna un identificatore di risultato ODBC + oppure <literal>falso</literal> se si verifica un errore. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>TABLE_OWNER</simpara></listitem> + <listitem><simpara>TABLE_NAME</simpara></listitem> + <listitem><simpara>GRANTOR</simpara></listitem> + <listitem><simpara>GRANTEE</simpara></listitem> + <listitem><simpara>PRIVILEGE</simpara></listitem> + <listitem><simpara>IS_GRANTABLE</simpara></listitem> + </itemizedlist> + </para> + <simpara> + I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, + TABLE_OWNER e TABLE_NAME. + </simpara> + <para> + L'argomento <parameter>nome_colonna</parameter> accetta dei + criteri di ricerca ('%' per indicare zero o più + caratteri e '_' per indicare un singolo carattere). + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-gettypeinfo"> + <refnamediv> + <refname>odbc_gettypeinfo</refname> + <refpurpose> + Restituisce un identificatore di risultato contenente informazioni + sui tipi di dati supportati dalla sorgente di dati. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_gettypeinfo</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>int <parameter><optional>tipo_dato</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Recupera informazioni sui tipi di dati supportati dalla + sorgente di dati. La funzione restituisce un identificatore + di risultato ODBC oppure <literal>falso</literal> su errore. + L'argomento opzionale <parameter>tipo_dato</parameter> può essere + utilizzato per restringere l'informazione su un singolo tipo. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>TYPE_NAME</simpara></listitem> + <listitem><simpara>DATA_TYPE</simpara></listitem> + <listitem><simpara>PRECISION</simpara></listitem> + <listitem><simpara>LITERAL_PREFIX</simpara></listitem> + <listitem><simpara>LITERAL_SUFFIX</simpara></listitem> + <listitem><simpara>CREATE_PARAMS</simpara></listitem> + <listitem><simpara>NULLABLE</simpara></listitem> + <listitem><simpara>CASE_SENSITIVE</simpara></listitem> + <listitem><simpara>SEARCHABLE</simpara></listitem> + <listitem><simpara>UNSIGNED_ATTRIBUTE</simpara></listitem> + <listitem><simpara>MONEY</simpara></listitem> + <listitem><simpara>AUTO_INCREMENT</simpara></listitem> + <listitem><simpara>LOCAL_TYPE_NAME</simpara></listitem> + <listitem><simpara>MINIMUM_SCALE</simpara></listitem> + <listitem><simpara>MAXIMUM_SCALE</simpara></listitem> + </itemizedlist> + </para> + <simpara>I campi di ordinamento delle righe risultanti sono DATA_TYPE e TYPE_NAME. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-primarykeys"> + <refnamediv> + <refname>odbc_primarykeys</refname> + <refpurpose> + Restituisce un identificatore di risultato che può essere utilizzato + per ricavare il nome della colonna che contiene la chiave primaria + della tabella. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_primarykeys</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter>qualifica</parameter></paramdef> + <paramdef>string <parameter>proprietario</parameter></paramdef> + <paramdef>string <parameter>tabella</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Restituisce il nome della colonna che contiene la chiave primaria + per la tabella. La funzione ritorna un identificatore di risultato + ODBC oppure <literal>falso</literal> se si verifica un errore. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>TABLE_OWNER</simpara></listitem> + <listitem><simpara>TABLE_NAME</simpara></listitem> + <listitem><simpara>COLUMN_NAME</simpara></listitem> + <listitem><simpara>KEY_SEQ</simpara></listitem> + <listitem><simpara>PK_NAME</simpara></listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-foreignkeys"> + <refnamediv> + <refname>odbc_foreignkeys</refname> + <refpurpose> + Restituisce l'elenco delle chiavi esterne per la tabella indicata, + oppure la lista delle chiavi esterne in altre tabelle che fanno + riferimento alla chiave primaria della tabella indicata. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_foreignkeys</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter>pk_qualifica</parameter></paramdef> + <paramdef>string <parameter>pk_proprietario</parameter></paramdef> + <paramdef>string <parameter>pk_tabella</parameter></paramdef> + <paramdef>string <parameter>fk_qualifica</parameter></paramdef> + <paramdef>string <parameter>fk_proprietario</parameter></paramdef> + <paramdef>string <parameter>fk_tabella</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione <function>odbc_foreignkeys</function> ritorna informazioni sulle + chiavi esterne. Restituisce un identificatore di risultato oppure + <literal>falso</literal> se si verifica un errore. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>PKTABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>PKTABLE_OWNER</simpara></listitem> + <listitem><simpara>PKTABLE_NAME</simpara></listitem> + <listitem><simpara>PKCOLUMN_NAME</simpara></listitem> + <listitem><simpara>FKTABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>FKTABLE_OWNER</simpara></listitem> + <listitem><simpara>FKTABLE_NAME</simpara></listitem> + <listitem><simpara>FKCOLUMN_NAME</simpara></listitem> + <listitem><simpara>KEY_SEQ</simpara></listitem> + <listitem><simpara>UPDATE_RULE</simpara></listitem> + <listitem><simpara>DELETE_RULE</simpara></listitem> + <listitem><simpara>FK_NAME</simpara></listitem> + <listitem><simpara>PK_NAME</simpara></listitem> + </itemizedlist> + </para> + <simpara> + Se l'argomento <parameter>pk_tabella</parameter> contiene il nome di una tabella, + la funzione <function>odbc_foreignkeys</function> ritorna una serie di righe + contenenti i dati della chiave primaria della tabella e di tutte le chiavi esterne + che hanno riferimenti a questa. + </simpara> + <simpara> + Se l'argomento <parameter>fk_tabella</parameter> contiene il nome di una tabella, + la funzione <function>odbc_foreignkeys</function> ritorna una serie di righe + contenenti i dati delle chiavi esterne della tabella e delle chiavi primarie + ( di altre tabelle ) a cui queste hanno riferimenti. + </simpara> + <simpara> + Se entrambi gli argomenti <parameter>pk_tabella</parameter> e + <parameter>fk_tabella</parameter> contengono nomi di tabelle, + <function>odbc_foreignkeys</function> restituisce le chiavi esterne + della tabella specificata in <parameter>fk_tabella</parameter> che hanno + riferimenti alla chiave primaria della tabella indicata in + <parameter>pk_tabella</parameter>. La funzione dovrebbe trovare almeno una chiave. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-procedures"> + <refnamediv> + <refname>odbc_procedures</refname> + <refpurpose> + Restituisce l'elenco delle procedure memorizzate in una specifica + sorgente di dati. La funzione ritorna un identificatore di risultato che + punta alle informazioni reperite. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_procedures</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> + <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> + <paramdef>string <parameter><optional>nome</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Si ottiene l'elenco di tutte le procedure presenti nei limiti richiesti. + La funzione restituisce un identificatore di risultato, + oppure &false; su errore. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>PROCEDURE_QUALIFIER</simpara></listitem> + <listitem><simpara>PROCEDURE_OWNER</simpara></listitem> + <listitem><simpara>PROCEDURE_NAME</simpara></listitem> + <listitem><simpara>NUM_INPUT_PARAMS</simpara></listitem> + <listitem><simpara>NUM_OUTPUT_PARAMS</simpara></listitem> + <listitem><simpara>NUM_RESULT_SETS</simpara></listitem> + <listitem><simpara>REMARKS</simpara></listitem> + <listitem><simpara>PROCEDURE_TYPE</simpara></listitem> + </itemizedlist> + </para> + <para> + Gli argomenti <parameter>proprietario</parameter> e <parameter>nome</parameter> + accettano dei criteri di ricerca ('%' per indicare zero o più + caratteri e '_' per indicare un singolo carattere). + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-procedurecolumns"> + <refnamediv> + <refname>odbc_procedurecolumns</refname> + <refpurpose> + Recupera informazioni sui parametri delle procedure. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_procedurecolumns</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter><optional>qualifica</optional></parameter></paramdef> + <paramdef>string <parameter><optional>proprietario</optional></parameter></paramdef> + <paramdef>string <parameter><optional>procedura</optional></parameter></paramdef> + <paramdef>string <parameter><optional>colonna</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + La funzione ritorna la lista dei parametri di input e di output e anche + delle colonne che concorrono al determinazione del risultato per le procedure + indicate. Viene restituito un identificatore di risultato oppure + &false; se si è un errore. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>PROCEDURE_QUALIFIER</simpara></listitem> + <listitem><simpara>PROCEDURE_OWNER</simpara></listitem> + <listitem><simpara>PROCEDURE_NAME</simpara></listitem> + <listitem><simpara>COLUMN_NAME</simpara></listitem> + <listitem><simpara>COLUMN_TYPE</simpara></listitem> + <listitem><simpara>DATA_TYPE</simpara></listitem> + <listitem><simpara>TYPE_NAME</simpara></listitem> + <listitem><simpara>PRECISION</simpara></listitem> + <listitem><simpara>LENGTH</simpara></listitem> + <listitem><simpara>SCALE</simpara></listitem> + <listitem><simpara>RADIX</simpara></listitem> + <listitem><simpara>NULLABLE</simpara></listitem> + <listitem><simpara>REMARKS</simpara></listitem> + </itemizedlist> + </para> + <simpara>I campi di ordinamento delle righe risultanti sono PROCEDURE_QUALIFIER, PROCEDURE_OWNER, + PROCEDURE_NAME e COLUMN_TYPE. + </simpara> + <para> + Gli argomenti <parameter>proprietario</parameter>, <parameter>procedura</parameter> + e <parameter>colonna</parameter> accettano dei + criteri di ricerca ('%' per indicare zero o più + caratteri e '_' per indicare un singolo carattere). + </para> + </refsect1> + </refentry> + + <refentry id="function.odbc-specialcolumns"> + <refnamediv> + <refname>odbc_specialcolumns</refname> + <refpurpose> + Restituisce sia il set di colonne che identificano in modo univoco + una riga nella tabella, sia colonne che sono automaticamente + aggiornate quando un qualsiasi campo della riga viene aggiornato + da una transazione. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_specialcolumns</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>int <parameter>tipo</parameter></paramdef> + <paramdef>string <parameter>qualifica</parameter></paramdef> + <paramdef>string <parameter>proprietario</parameter></paramdef> + <paramdef>string <parameter>tabella</parameter></paramdef> + <paramdef>int <parameter>visibilità</parameter></paramdef> + <paramdef>int <parameter>nullable</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Quando l'argomento tipo è impostato a SQL_BEST_ROWID, + <function>odbc_specialcolumns</function> restituisce la colonna + o le colonne che identificano in modo univoco ciascuna riga nella tabella. + </simpara> + <simpara> + Quando l'argomento tipo è impostato a SQL_ROWVER, + <function>odbc_specialcolumns</function> restituisce la colonna + o il set di colonne ottimali, attraverso cui, ottenendo i valori + da dette colonne, è possibile identificare in modo univoco ciascun record + della tabella indicata. + </simpara> + <simpara> + La funzione restituisce un identificatore di risultato ODBC, + oppure <literal>falso</literal> su errore. + </simpara> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>SCOPE</simpara></listitem> + <listitem><simpara>COLUMN_NAME</simpara></listitem> + <listitem><simpara>DATA_TYPE</simpara></listitem> + <listitem><simpara>TYPE_NAME</simpara></listitem> + <listitem><simpara>PRECISION</simpara></listitem> + <listitem><simpara>LENGTH</simpara></listitem> + <listitem><simpara>SCALE</simpara></listitem> + <listitem><simpara>PSEUDO_COLUMN</simpara></listitem> + </itemizedlist> + </para> + <simpara> + Le righe del risultato sono ordinate in base alla colonna SCOPE. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.odbc-statistics"> + <refnamediv> + <refname>odbc_statistics</refname> + <refpurpose>Recupera informazioni statistiche sulla tabella</refpurpose> + </refnamediv> + <refsect1> + <title>Descrizione</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>odbc_statistics</function></funcdef> + <paramdef>int <parameter>id_connessione</parameter></paramdef> + <paramdef>string <parameter>qualifica</parameter></paramdef> + <paramdef>string <parameter>proprietario</parameter></paramdef> + <paramdef>string <parameter>nome_tabella</parameter></paramdef> + <paramdef>int <parameter>unico</parameter></paramdef> + <paramdef>int <parameter>precisione</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Si ottengono informazioni statistiche sulla tabella e i propri indici. + La funzione restituisce un identificatore di risultato ODBC, + oppure <literal>falso</literal> su errore. + </para> + <para> + Le righe risultanti dall'elaborazione contengono i seguenti campi: + <itemizedlist> + <listitem><simpara>TABLE_QUALIFIER</simpara></listitem> + <listitem><simpara>TABLE_OWNER</simpara></listitem> + <listitem><simpara>TABLE_NAME</simpara></listitem> + <listitem><simpara>NON_UNIQUE</simpara></listitem> + <listitem><simpara>INDEX_QUALIFIER</simpara></listitem> + <listitem><simpara>INDEX_NAME</simpara></listitem> + <listitem><simpara>TYPE</simpara></listitem> + <listitem><simpara>SEQ_IN_INDEX</simpara></listitem> + <listitem><simpara>COLUMN_NAME</simpara></listitem> + <listitem><simpara>COLLATION</simpara></listitem> + <listitem><simpara>CARDINALITY</simpara></listitem> + <listitem><simpara>PAGES</simpara></listitem> + <listitem><simpara>FILTER_CONDITION</simpara></listitem> + </itemizedlist> + </para> + <simpara> + I campi di ordinamento delle righe risultanti sono NON_UNIQUE, TYPE, INDEX_QUALIFIER, + INDEX_NAME e SEQ_IN_INDEX. + </simpara> + </refsect1> + </refentry> + + </reference> + +<!-- Mantenere questo commento alla fine del file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> + Index: phpdoc/pt_BR/functions/url.xml diff -u phpdoc/pt_BR/functions/url.xml:1.2 phpdoc/pt_BR/functions/url.xml:1.3 --- phpdoc/pt_BR/functions/url.xml:1.2 Sat Jun 23 16:35:16 2001 +++ phpdoc/pt_BR/functions/url.xml Sat Jul 7 19:11:37 2001 @@ -1,175 +1,175 @@ - <reference id="ref.url"> - <title>Funções URL</title> - <titleabbrev>URLs</titleabbrev> - - <refentry id="function.base64-decode"> - <refnamediv> - <refname>base64_decode</refname> - <refpurpose>Decodifica dados codificados com MIME base64</refpurpose> - </refnamediv> - <refsect1> - <title>Descrição</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>base64_decode</function></funcdef> - <paramdef>string <parameter>encoded_data</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>base64_decode</function> decodes - <parameter>encoded_data</parameter> e retorna o dado - original. O retorno pode ser binário. - </para> - <para> - Veja também: <function>base64_encode</function>, RFC-2045 seção - 6.8. - </para> - </refsect1> - </refentry> - - <refentry id="function.base64-encode"> - <refnamediv> - <refname>base64_encode</refname> - <refpurpose>Codifica dados com MIME base64</refpurpose> - </refnamediv> - <refsect1> - <title>Descrição</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>base64_encode</function></funcdef> - <paramdef>string <parameter>dados</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>base64_encode</function> returns - <parameter>Dado</parameter> codificado com base64. Esta codificação - é designada para que dados binários durem no transporte sobre - camadas de transorte que não são 8-bit clean, como mensagens de e-mail. - </para> - <para> - Dados codificados na Base-64 tem aproximadamente 33% mais espaço que dos dados - originais.</para> - <para> - Veja também: - <function>base64_decode</function>, - <function>chunk_split</function>, - RFC-2045 seção 6.8. - </para> - </refsect1> - </refentry> - - <refentry id="function.parse-url"> - <refnamediv> - <refname>parse_url</refname> - <refpurpose>Separa uma URL e retorna seus componentes</refpurpose> - </refnamediv> - <refsect1> - <title>Descrição</title> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>parse_url</function></funcdef> - <paramdef>string <parameter>url</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Esta função retorna um array associativo qualquer um dos vários - componentes de uma URL que estão presentes. Isto inclui - "scheme", "host", "port", "user", "pass", "path", "query", e - "fragment". - </para> - </refsect1> - </refentry> - - <refentry id="function.urldecode"> - <refnamediv> - <refname>urldecode</refname> - <refpurpose>Decodifica uma URL codificada</refpurpose> - </refnamediv> - <refsect1> - <title>Descrição</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>urldecode</function></funcdef> - <paramdef>string <parameter>str</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Decodifica qualquer <literal>%<replaceable>##</replaceable></literal> - codificado na string. A string decodificada é o valor de retorno. - <example> - <title><function>urldecode</function> exemplo</title> - <programlisting role="php"> -$a = split ('&amp;', $querystring); -$i = 0; -while ($i &lt; count ($a)) { - $b = split ('=', $a [$i]); - echo 'Value for parameter ', htmlspecialchars (urldecode ($b [0])), - ' is ', htmlspecialchars (urldecode ($b [1])), "&lt;BR>"; - $i++; -} - </programlisting> - </example> - </para> - <para> - Veja também <function>urlencode</function>. - </para> - </refsect1> - </refentry> - - <refentry id="function.urlencode"> - <refnamediv> - <refname>urlencode</refname> - <refpurpose>Codifica uma string URL</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>urlencode</function></funcdef> - <paramdef>string <parameter>str</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <para> - Retorna uma string onde todos caracteres não-alfanuméricos exceto - <literal>-_.</literal> é substituido por um sinal de porcento - (<literal>%</literal>) seguidos por dois digítos hexadecimais e espaços - codificados como um sinal de 'mais' (<literal>+</literal>). É codificando - o mesmo caminho que um dado enviados por um formulário WWW é codificado , que é a - mesma coisa como em um tipo de mídia - <literal>application/x-www-form-urlencoded</literal>. - Isto difere da codificação RFC1738 (veja - <function>rawurlencode</function>) por rasões históricas, - espaçoes são codificados como um sinal de 'mais' (+). Esta função é - conveniente quando codificado uma string para ser usada em uma parte de consulta - em uma URL, como um conveniente meio de passar variáveis para uma próxima página: - <example> - <title><function>urlencode</function> exemplo</title> - <programlisting role="php"> -echo '&lt;A HREF="mycgi?foo=', urlencode ($userinput), '">'; - </programlisting> - </example> - </para> - <para> - Veja também <function>urldecode</function>. - </para> - </refsect1> - </refentry> - - </reference> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> + <reference id="ref.url"> + <title>Funções URL</title> + <titleabbrev>URLs</titleabbrev> + + <refentry id="function.base64-decode"> + <refnamediv> + <refname>base64_decode</refname> + <refpurpose>Decodifica dados codificados com MIME base64</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>base64_decode</function></funcdef> + <paramdef>string <parameter>encoded_data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>base64_decode</function> decodes + <parameter>encoded_data</parameter> e retorna o dado + original. O retorno pode ser binário. + </para> + <para> + Veja também: <function>base64_encode</function>, RFC-2045 seção + 6.8. + </para> + </refsect1> + </refentry> + + <refentry id="function.base64-encode"> + <refnamediv> + <refname>base64_encode</refname> + <refpurpose>Codifica dados com MIME base64</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>base64_encode</function></funcdef> + <paramdef>string <parameter>dados</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>base64_encode</function> returns + <parameter>Dado</parameter> codificado com base64. Esta codificação + é designada para que dados binários durem no transporte sobre + camadas de transorte que não são 8-bit clean, como mensagens de e-mail. + </para> + <para> + Dados codificados na Base-64 tem aproximadamente 33% mais espaço que dos dados + originais.</para> + <para> + Veja também: + <function>base64_decode</function>, + <function>chunk_split</function>, + RFC-2045 seção 6.8. + </para> + </refsect1> + </refentry> + + <refentry id="function.parse-url"> + <refnamediv> + <refname>parse_url</refname> + <refpurpose>Separa uma URL e retorna seus componentes</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>parse_url</function></funcdef> + <paramdef>string <parameter>url</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Esta função retorna um array associativo qualquer um dos vários + componentes de uma URL que estão presentes. Isto inclui + "scheme", "host", "port", "user", "pass", "path", "query", e + "fragment". + </para> + </refsect1> + </refentry> + + <refentry id="function.urldecode"> + <refnamediv> + <refname>urldecode</refname> + <refpurpose>Decodifica uma URL codificada</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>urldecode</function></funcdef> + <paramdef>string <parameter>str</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Decodifica qualquer <literal>%<replaceable>##</replaceable></literal> + codificado na string. A string decodificada é o valor de retorno. + <example> + <title><function>urldecode</function> exemplo</title> + <programlisting role="php"> +$a = split ('&amp;', $querystring); +$i = 0; +while ($i &lt; count ($a)) { + $b = split ('=', $a [$i]); + echo 'Value for parameter ', htmlspecialchars (urldecode ($b [0])), + ' is ', htmlspecialchars (urldecode ($b [1])), "&lt;BR>"; + $i++; +} + </programlisting> + </example> + </para> + <para> + Veja também <function>urlencode</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.urlencode"> + <refnamediv> + <refname>urlencode</refname> + <refpurpose>Codifica uma string URL</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>urlencode</function></funcdef> + <paramdef>string <parameter>str</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna uma string onde todos caracteres não-alfanuméricos exceto + <literal>-_.</literal> é substituido por um sinal de porcento + (<literal>%</literal>) seguidos por dois digítos hexadecimais e espaços + codificados como um sinal de 'mais' (<literal>+</literal>). É codificando + o mesmo caminho que um dado enviados por um formulário WWW é codificado , que é a + mesma coisa como em um tipo de mídia + <literal>application/x-www-form-urlencoded</literal>. + Isto difere da codificação RFC1738 (veja + <function>rawurlencode</function>) por rasões históricas, + espaçoes são codificados como um sinal de 'mais' (+). Esta função é + conveniente quando codificado uma string para ser usada em uma parte de consulta + em uma URL, como um conveniente meio de passar variáveis para uma próxima página: + <example> + <title><function>urlencode</function> exemplo</title> + <programlisting role="php"> +echo '&lt;A HREF="mycgi?foo=', urlencode ($userinput), '">'; + </programlisting> + </example> + </para> + <para> + Veja também <function>urldecode</function>. + </para> + </refsect1> + </refentry> + + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +-->