Description
string imap_fetchbody(int imap_stream, int msg_number, int part_number, flags flags);
This function causes a fetch of a particular section of the body of the specified messages as a text string and returns that text string. The section specification is a string of integers delimited by period which index into a body part list as per the IMAP4 specification. Body parts are not decoded by this function.
The options for imap_fetchbody ()e a bitmask with one or more of the following
FT_UID - The msgono is a UID
FT_PEEK - Do not set the \Seen flag if not already set
FT_UID - The return string is in "internal" format, without any attempt to canonicalize CRLF
imap_fetchstructure
imap_fetchstructure -- Read the structure of a particular message
Description
array imap_fetchstructure(int imap_stream, int msg_number);
This function causes a fetch of all the structured information for the given msg_number. The returned value is an object with following elements.
type, encoding, ifsubtype, subtype, ifdescription, description, ifid,
id, lines, bytes, ifparameters
It also returns an array of objects called parameters[]. This object has following properties.
attribute, value
In case of multipart, it also returns an array of objects of all the properties, called parts[].
imap_header
imap_header -- Read the header of the message
Description
object imap_header(int imap_stream, int msg_number, int fromlength, int subjectlength, int defaulthost);
This function returns an object of various header elements
remail,date,Date,subject,Subject,in_reply_to,message_id,newsgroups,
followup_to,references
toaddress (full to: line, up to 1024 characters)
to[] (returns an array of objects from the To line, containing:)
personal
adl
mailbox
host
fromaddress (full from: line, up to 1024 characters)
from[] (returns an array of objects from the From line, containing:)
personal
adl
mailbox
host
ccaddress (full cc: line, up to 1024 characters)
cc[] (returns an array of objects from the Cc line, containing:)
personal
adl
mailbox
host
bccaddress (full bcc line, up to 1024 characters)
bcc[] (returns an array of objects from the Bcc line, containing:)
personal
adl
mailbox
host
reply_toaddress (full reply_to: line, up to 1024 characters)
reply_to[] (returns an array of objects from the Reply_to line, containing:)
personal
adl
mailbox
host
senderaddress (full sender: line, up to 1024 characters)
sender[] (returns an array of objects from the sender line, containing:)
personal
adl
mailbox
host
return_path (full return-path: line, up to 1024 characters)
return_path[] (returns an array of objects from the return_path line, containing:)
personal
adl
mailbox
host
udate ( mail message date in unix time)
fetchfrom (from line formatted to fit fromlength characters)
fetchsubject (subject line formatted to fit subjectlength characters)
imap_headers
imap_headers -- Returns headers for all messages in a mailbox
Description
array imap_headers(int imap_stream);
Returns an array of string formatted with header info. One element per mail message.
imap_listmailbox
imap_listmailbox -- Read the list of mailboxes
Description
array imap_listmailbox(int imap_stream, string ref, string pat);
Returns an array containing the names of the mailboxes.
imap_listsubscribed
imap_listsubscribed -- List all the subscribed mailboxes
Description
array imap_listsubscribed(int imap_stream, string ref, string pattern);
Returns an array of all the mailboxes that you have subscribed. The ref and pattern arguments specify the base location to search from and the pattern the mailbox name must match.
imap_mail_copy
imap_mail_copy -- Copy specified messages to a mailbox
Description
int imap_mail_copy(int imap_stream, string msglist, string mbox, int flags);
Returns true on success and false on error.
Copies mail messages specified by msglist to specified mailbox. msglist is a range not just message numbers.
flags is a bitmask of one or more of
CP_UID - the sequence numbers contain UIDS
CP_MOVE - Delete the messages from the current mailbox after copying
imap_mail_move
imap_mail_move -- Move specified messages to a mailbox
Description
int imap_mail_move(int imap_stream, string msglist, string mbox);
Moves mail messages specified by msglist to specified mailbox. msglist is a range not just message numbers.
Returns true on success and false on error.
imap_num_msg
imap_num_msg -- Gives the number of messages in the current mailbox
Description
int imap_num_msg(void);
Return the number of messages in the current mailbox.
imap_num_recent
imap_num_recent -- Gives the number of recent messages in current mailbox
Description
int imap_num_recent(int imap_stream);
Returns the number of recent messages in the current mailbox.
imap_open
imap_open -- Open an IMAP stream to a mailbox
Description
int imap_open(string mailbox, string username, string password, int flags);
Returns an IMAP stream on success and false on error. This function can also be used to open streams to POP3 and NNTP servers. To connect to an IMAP server running on port 143 on the local machine, do the following:
$mbox = imap_open("{localhost:143}INBOX","user_id","password");
To connect to a POP3 server on port 110 on the local server, use:
$mbox = imap_open("{localhost/pop3:110}INBOX","user_id","password");
To connect to an NNTP server on port 119 on the local server, use:
$nntp = imap_open("{localhost/nntp:119}comp.test","","");
To connect to a remote server replace "localhost" with the name or the IP address of the server you want to connect to.
The options are a bit mask with one or more of the following:
OP_READONLY - Open mailbox read-only
OP_ANONYMOUS - Dont use or update a .newsrc for news
OP_HALFOPEN - For IMAP and NNTP names, open a connection but dont open a mailbox
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close
imap_ping
imap_ping -- Check if the IMAP stream is still active
Description
int imap_ping(int imap_stream);
Returns true if the stream is still alive, false otherwise.
imap_ping() function pings the stream to see it is still active. It may discover new mail; this is the preferred method for a periodic "new mail check" as well as a "keep alive" for servers which have inactivity timeout.
imap_renamemailbox
imap_renamemailbox -- Rename an old mailbox to new mailbox
Description
int imap_renamemailbox(int imap_stream, string old_mbox, string new_mbox);
This function renames on old mailbox to new mailbox.
Returns true on success and false on error.
imap_reopen
imap_reopen -- Reopen IMAP stream to new mailbox
Description
int imap_reopen(string imap_stream, string mailbox, string [flags]);
Returns true on success and false on error.
This function reopens the specified stream to new mailbox.
the options are a bit mask with one or more of the following:
OP_READONLY - Open mailbox read-only
OP_ANONYMOUS - Dont use or update a .newsrc for news
OP_HALFOPEN - For IMAP and NNTP names, open a connection but dont open a mailbox
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close
imap_subscribe
imap_subscribe -- Subscribe to a mailbox
Description
int imap_subscribe(int imap_stream, string mbox);
Subscribe to a new mailbox.
Returns true on success and false on error.
imap_undelete
imap_undelete -- Unmark the message which is marked deleted
Description
int imap_undelete(int imap_stream, int msg_number);
This function removes the deletion flag for a specified message, which is set by imap_delete().
Returns true on success and false on error.
imap_unsubscribe
imap_unsubscribe -- Unsubscribe from a mailbox
Description
int imap_unsubscribe(int imap_stream, string mbox);
Unsubscribe from a specified mailbox.
Returns true on success and false on error.
imap_qprint
imap_qprint -- Convert a quoted-printable string to an 8 bit string
Description
string imap_qprint(string string);
Convert a quoted-printable string to an 8 bit string
Returns an 8 bit (binary) string
imap_8bit
imap_8bit -- Convert an 8bit string to a quoted-printable string.
Description
string imap_8bit(string string);
Convert an 8bit string to a quoted-printable string.
Returns a quoted-printable string
imap_binary
imap_binary -- Convert an 8bit string to a base64 string.
Description
string imap_binary(string string);
Convert an 8bit string to a base64 string.
Returns a base64 string
imap_scanmailbox
imap_scanmailbox -- Read the list of mailboxes, takes a string to search for in the text of the mailbox
Description
array imap_scanmailbox(int imap_stream, string string);
Returns an array containing the names of the mailboxes that have string in the text of the mailbox.
imap_mailboxmsginfo
imap_mailboxmsginfo -- Get information about the current mailbox
Description
array imap_mailboxmsginfo(int imap_stream);
Returns information about the current mailbox. Returns FALSE on failure.
The imap_mailboxmsginfo() function checks the current mailbox status on the server and returns the information in an object with following properties.
Date : date of the message
Driver : driver
Mailbox : name of the mailbox
Nmsgs : number of messages
Recent : number of recent messages
Unread : number of unread messages
Size : mailbox size
imap_rfc822_write_address
imap_rfc822_write_address -- Returns a properly formatted email address given the mailbox, host, and personal info.
Description
string imap_rfc822_write_address(string mailbox, string host, string personal);
Returns a properly formatted email address given the mailbox, host, and personal info.
imap_rfc822_parse_adrlist
imap_rfc822_parse_adrlist -- Parses an address string
Description
string imap_rfc822_parse_adrlist(string address, string default_host);
This function parses the address tring and for each address, returns an array of objects. The 4 objects are:
mailbox - the mailbox name (username)
host - the host name
personal - the personal name
adl - at domain source route
imap_setflag_full
imap_setflag_full -- Sets flags on messages
Description
string imap_setflag_full(int stream, string sequence, string flag, string options);
This function causes a store to add the specified flag to the flags set for the messages in the specified sequence.
The options are a bit mask with one or more of the following:
ST_UID The sequence argument contains UIDs instead of
sequence numbers
imap_clearflag_full
imap_clearflag_full -- Clears flags on messages
Description
string imap_clearflag_full(int stream, string sequence, string flag, string options);
This function causes a store to delete the specified flag to the flags set for the messages in the specified sequence.
The options are a bit mask with one or more of the following:
ST_UID The sequence argument contains UIDs instead of
sequence numbers
imap_sort
imap_sort --
Description
string imap_sort(int stream, int criteria, int reverse, int options);
Returns an array of message numbers sorted by the given parameters
Rev is 1 for reverse-sorting.
Criteria can be one (and only one) of the following:
SORTDATE message Date
SORTARRIVAL arrival date
SORTFROM mailbox in first From address
SORTSUBJECT message Subject
SORTTO mailbox in first To address
SORTCC mailbox in first cc address
SORTSIZE size of message in octets
The flags are a bitmask of one or more of the following:
SE_UID Return UIDs instead of sequence numbers
SE_NOPREFETCH Don't prefetch searched messages.
imap_fetchheader
imap_fetchheader -- Returns header for a message
Description
stringimap_fetchheader(int imap_stream, int msgno, int flags);
This function causes a fetch of the complete, unfiltered RFC 822 format header of the specified message as a text string and returns that text string.
The options are:
FT_UID The msgno argument is a UID
FT_INTERNAL The return string is in "internal" format,
without any attempt to canonicalize to CRLF
newlines
FT_PREFETCHTEXT The RFC822.TEXT should be pre-fetched at the
same time. This avoids an extra RTT on an
IMAP connection if a full message text is
desired (e.g. in a "save to local file"
operation)
imap_uid
imap_uid -- This function returns the UID for the given message sequence number.
Description
string imap_uid(string mailbox, int msgno);
This function returns the UID for the given message sequence number
XVIII. PHP options & information
Table of Contents
error_log
error_reporting
getenv
get_cfg_var
get_current_user
get_magic_quotes_gpc
get_magic_quotes_runtime
getlastmod
getmyinode
getmypid
getmyuid
phpinfo
phpversion
putenv
set_magic_quotes_runtime
set_time_limit
error_log
error_log -- send an error message somewhere
Description
int error_log(string message, int message_type, string [destination], string [extra_headers]);
Sends an error message to the web server's error log, a TCP port or to a file. The first parameter, message, is the error message that should be logged. The second parameter, message_type says where the message should go:
Table 1. error_log() log types
0 message is sent to PHP's system logger, using the Operating System's system logging mechanism or a file, depending on what the error_log configuration directive is set to.
1 message is sent by email to the address in the destination parameter. This is the only message type where the fourth parameter, extra_headers is used. This message type uses the same internal function as Mail() does.
2 message is sent through the PHP debugging connection. This option is only available if remote debugging has been enabled. In this case, the destination parameter specifies the host name or IP address and optionally, port number, of the socket receiving the debug information.
3 message is appended to the file destination.
Example 1. error_log() examples
// Send notification through the server log if we can not
// connect to the database.
if (!Ora_Logon($username, $password)) {
error_log("Oracle database not available!", 0);
}
// Notify administrator by email if we run out of FOO
if (!($foo = allocate_new_foo()) {
error_log("Big trouble, we're all out of FOOs!", 1,
"operator@mydomain.com");
}
// other ways of calling error_log():
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");
error_reporting
error_reporting -- set which PHP errors are reported
Description
int error_reporting(int [level]);
Sets PHP's error reporting level and returns the old level. The error reporting level is a bitmask of the following values (follow the links for the internal values to get their meanings):
Table 1. error_reporting() bit values
value internal name
1 E_ERROR
2 E_WARNING
4 E_PARSE
8 E_NOTICE
16 E_CORE_ERROR
32 E_CORE_WARNING
getenv
getenv -- Get the value of an environment variable.
Description
string getenv(string varname);
Returns the value of the environment variable varname, or false on an error.
$ip = getenv("REMOTE_ADDR"); // get the ip number from the user
get_cfg_var
get_cfg_var -- Get the value of a PHP configuration option.
Description
string get_cfg_var(string varname);
Returns the current value of the PHP configuration variable specified by varname, or false if an error occurs.
It will not return configuration information set when the PHP was compiled, or read from an Apache configuration file (using the php3_configuration_option directives).
To check whether the system is using a php3.ini file, try retrieving the value of the cfg_file_path configuration setting. If this is available, a php3.ini file is being used.
get_current_user
get_current_user -- Get the name of the owner of the current PHP script.
Description
string get_current_user(void);
Returns the name of the owner of the current PHP script.
See also getmyuid(), getmypid(), getmyinode(), and getlastmod().
get_magic_quotes_gpc
get_magic_quotes_gpc -- Get the current active configuration setting of magic quotes gpc.
Description
long get_magic_quotes_gpc(void);
Returns the current active configuration setting of magic_quotes_gpc. (0 for off, 1 for on)
See also get_magic_quotes_runtime(), set_magic_quotes_runtime().
get_magic_quotes_runtime
get_magic_quotes_runtime -- Get the current active configuration setting of magic_quotes_runtime.
Description
long get_magic_quotes_runtime(void);
Returns the current active configuration setting of magic_quotes_runtime. (0 for off, 1 for on)
See also get_magic_quotes_gpc(), set_magic_quotes_runtime().
getlastmod
getlastmod -- Get time of last page modification.
Description
int getlastmod(void);
Returns the time of the last modification of the current page. The value returned is a Unix timestamp, suitable for feeding to date(). Returns false on error.
Example 1. getlastmod() example
// outputs e.g. 'Last modified: March 04 1998 20:43:59.'
echo "Last modified: ".date( "F d Y H:i:s.", getlastmod() );
See alse date(), getmyuid(), get_current_user(), getmyinode(), and getmypid().
getmyinode
getmyinode -- Get the inode of the current script.
Description
int getmyinode(void);
Returns the current script's inode, or false on error.
See also getmyuid(), get_current_user(), getmypid(), and getlastmod().
getmypid
getmypid -- Get PHP's process ID.
Description
int getmypid(void);
Returns the current PHP process ID, or false on error.
Note that when running as a server module, separate invocations of the script are not guaranteed to have distinct pids.
See also getmyuid(), get_current_user(), getmyinode(), and getlastmod().
getmyuid
getmyuid -- Get PHP script owner's UID.
Description
int getmyuid(void);
Returns the user ID of the current script, or false on error.
See also getmypid(), get_current_user(), getmyinode(), and getlastmod().
phpinfo
phpinfo -- Output lots of PHP information.
Description
int phpinfo(void);
Outputs a large amount of information about the current state of PHP. This includes information about PHP compilation options and extensions, the PHP version, server information and environment (if compiled as a module), the PHP environment, OS version information, paths, master and local values of configuration options, HTTP headers, and the GNU Public License.
See also phpversion().
phpversion
phpversion -- Get the current PHP version.
Description
string phpversion(void);
Returns a string containing the version of the currently running PHP parser.
Example 1. phpversion() example
// prints e.g. 'Current PHP version: 3.0rel-dev'
echo "Current PHP version: ".phpversion();
See also phpinfo().
putenv
putenv -- Set the value of an environment variable.
Description
void putenv(string setting);
Adds setting to the environment.
Example 1. Setting an Environment Variable
putenv("UNIQID=$uniqid");
set_magic_quotes_runtime
set_magic_quotes_runtime -- Set the current active configuration setting of magic_quotes_runtime.
Description
long get_magic_quotes_runtime(int new_setting);
Set the current active configuration setting of magic_quotes_runtime. (0 for off, 1 for on)
See also get_magic_quotes_gpc(), get_magic_quotes_runtime().
set_time_limit
set_time_limit -- limit the maximum execution time
Description
void set_time_limit(int seconds);
Set the number of seconds a script is allowed to run. If this is reached, the script returns a fatal error. The default limit is 30 seconds or, if it exists, the max_execution_time value defined in php3.ini. If seconds is set to zero, no time limit is imposed.
When called, set_time_limit() restarts the timeout counter from zero. In other words, if the timeout is the default 30 seconds, and 25 seconds into script execution a call such as set_time_limit( 20 ) is made, the script will run for a total of 45 seconds before timing out.
XIX. Informix Functions
Table of Contents
ifx_connect
ifx_pconnect
ifx_close
ifx_query
ifx_prepare
ifx_do
ifx_error
ifx_errormsg
ifx_affected_rows
ifx_fetch_row
ifx_htmltbl_result
ifx_fieldtypes
ifx_fieldproperties
ifx_num_fields
ifx_num_rows
ifx_free_result
ifx_create_char
ifx_free_char
ifx_update_char
ifx_get_char
ifx_create_blob
ifx_copy_blob
ifx_free_blob
ifx_get_blob
ifx_update_blob
ifx_blobinfile_mode
ifx_textasvarchar
ifx_byteasvarchar
ifx_nullformat
ifxus_create_slob
ifx_free_slob
ifxus_close_slob
ifxus_open_slob
ifxus_tell_slob
ifxus_seek_slob
ifxus_read_slob
ifxus_write_slob
The Informix driver for Online (ODS) 7.x, SE 7.x and Universal Server (IUS) 9.x is implemented in "functions/ifx.ec" and "functions/php3_ifx.h". At the moment of writing ODS 7.2 support is fairly complete, with full BLOB support. IUS 9.1 support is partly finished: the new data types are there, but SLOBS support is still under construction.
Configuration notes:
Before you run the "configure" script, make sure that the "INFORMIXDIR" variable has been set.
The configure script will autodetect the libraries and include directories, if you run "configure --with_informix=yes". You can overide this detection by specifying "IFX_LIBDIR", "IFX_LIBS" and "IFX_INCDIR" in the environment. The configure script will also try to detect your Informix server version. It will set the "HAVE_IFX_IUS" conditional compilation variable if your Informix version >= 9.00.
Some notes on the use of BLOBs:
The current version (September 18, 1998) has complete select/insert/update support for BLOB columns.
BLOBs are normally addressed by integer BLOB identifiers. Select queries return a "blob id" for every BYTE and TEXT column. You can get at the contents with "string_var = ifx_get_blob($blob_id);" if you choose to get the BLOBs in memory (with : "ifx_blobinfile(0);"). If you prefer to receive the content of BLOB columns in a file, use "ifx_blobinfile(1);", and "ifx_get_blob($blob_id);" will get you the filename. Use normal file I/O to get at the blob contents.
For insert/update queries you must create these "blob id's" yourself with "ifx_create_blob(..);". You then plug the blob id's into an array, and replace the blob columns with a question mark (?) in the query string. For updates/inserts, you are responsible for setting the blob contents with ifx_update_blob(...).
The behaviour of BLOB columns can be altered by configuration variables that also can be set at runtime :
configuration variable : ifx.textasvarchar
configuration variable : ifx.byteasvarchar
runtime functions :
ifx_textasvarchar(0) : use blob id's for select queries with TEXT columns
ifx_byteasvarchar(0) : use blob id's for select queries with BYTE columns
ifx_textasvarchar(1) : return TEXT columns as if they were VARCHAR columns, without the use of blob id's for select queries.
ifx_byteasvarchar(1) : return BYTE columns as if they were VARCHAR columns, without the use of blob id's for select queries.
configuration variable : ifx.blobinfile
runtime function :
ifx_blobinfile_mode(0) : return BYTE columns in memory, the blob id lets you get at the contents.
ifx_blobinfile_mode(1) : return BYTE columns in a file, the blob id lets you get at the file name.
If you set ifx_text/byteasvarchar to 1, you can use TEXT and BYTE columns in select queries just like normal (but rather long) VARCHAR fields. Since all strings are "counted" in PHP3, this remains "binary safe". It is up to you to handle this correctly. The returned data can contain anything, you are responsible for the contents.
If you set ifx_blobinfile to 1, use the file name returned by ifx_get_blob(..) to get at the blob contents. Note that in this case YOU ARE RESPONSIBLE FOR DELETING THE TEMPORARY FILES CREATED BY INFORMIX when fetching the row. Every new row fetched will create new temporary files for every BYTE column.
The location of the temporary files can be influenced by the environment variable "blobdir", default is "." (the current directory). Something like : putenv(blobdir=tmpblob"); will ease the cleaning up of temp files accidentally left behind (their names all start with "blb").
Automatically trimming "char" (SQLCHAR and SQLNCHAR) data:
This can be set with a configuration variable :
ifx.charasvarchar : if set to 1 trailing spaces will be automatically trimmed
ifx_connect
ifx_connect -- Open Informix server connection
Description
int ifx_connect(string [database] , string [userid] , string [password] );
Returns an connection identifier on success, or FALSE on error.
ifx_connect() establishes a connection to an Informix server. All of the arguments are optional, and if they're missing, defaults are taken from values supplied in php3.ini (ifx.default_host for the host (Informix libraries will use $INFORMIXSERVER environment value if not defined), ifx.default_user for user, ifx.default_password for the password (none if not defined).
In case a second call is made to ifx_connect() with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned.
The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling ifx_close().
See also ifx_pconnect(), and ifx_close().
Example 1. Connect to a Informix database
$conn_id = ifx_pconnect (mydb@ol_srv1, "imyself", "mypassword");
ifx_pconnect
ifx_pconnect -- Open persistent Informix connection
Description
int ifx_pconnect(string [database] , string [userid] , string [password] );
Returns: A positive Informix persistent link identifier on success, or false on error
ifx_pconnect() acts very much like ifx_connect() with two major differences.
This function behaves exactly like ifx_connect() when PHP is not running as an Apache module. First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (ifx_close() will not close links established by ifx_pconnect()).
This type of links is therefore called 'persistent'.
See also: ifx_connect().
ifx_close
ifx_close -- Close Informix connection
Description
int ifx_close(int [link_identifier] );
Returns: always true.
ifx_close() closes the link to an Informix database that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed.
Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution.
ifx_close() will not close persistent links generated by ifx_pconnect().
See also: ifx_connect(), and ifx_pconnect().
Example 1. Closing a Informix connection
$conn_id = ifx_connect (mydb@ol_srv, "itsme", "mypassword");
... some queries and stuff ...
ifx_close($conn_id);
ifx_query
ifx_query -- Send Informix query
Description
int ifx_query(string query, int [link_identifier] , int [cursor_type] , mixed [blobidarray] );
Returns: A positive Informix result identifier on success, or false on error.
An integer "result_id" used by other functions to retrieve the query results. Sets "affected_rows" for retrieval by the ifx_affected_rows() function.
ifx_query() sends a query to the currently active database on the server that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed. If no link is open, the function tries to establish a link as if ifx_connect() was called, and use it.
Executes query on connection conn_id. For "select-type" queries a cursor is declared and opened. The optional cursor_type parameter allows you to make this a "scroll" and/or "hold" cursor. It's a mask and can be either IFX_SCROLL, IFX_HOLD, or both or'ed together. Non-select queries are "execute immediate".
For either query type the number of (estimated or real) affected rows is saved for retrieval by ifx_affected_rows().
If you have BLOB (BYTE or TEXT) columns in an update query, you can add a blobidarray parameter containing the corresponding "blob ids", and you should replace those columns with a "?" in the query text.
If the contents of the TEXT (or BYTE) column allow it, you can also use "ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)". This allows you to treat TEXT (or BYTE) columns just as if they were ordinary (but long) VARCHAR columns for select queries, and you don't need to bother with blob id's.
With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default situation), select queries will return BLOB columns as blob id's (integer value). You can get the value of the blob as a string or file with the blob functions (see below).
See also: ifx_connect().
Example 1. Show all rows of the "orders" table as a html table
ifx_textasvarchar(1); // use "text mode" for blobs
$res_id = ifx_query("select * from orders", $conn_id);
if (! $res_id) {
printf("Can't select orders : %s\n<br>%s<br>\n",
ifx_error();
ifx_errormsg();
die;
}
ifx_htmltbl_result($res_id, "border=\"1\");
ifx_free_result($res_id);
Example 2. Insert some values into the "catalog" table
// create blob id's for a byte and text column
$textid = ifx_create_blob(0, 0, "Text column in memory");
$byteid = ifx_create_blob(1, 0, "Byte column in memory");
// store blob id's in a blobid array
$blobidarray[] = $textid;
$blobidarray[] = $byteid;
// launch query
$query = "insert into catalog (stock_num, manu_code, " .
"cat_descr,cat_picture) values(1,'HRO',?,?)";
$res_id = ifx_query($query, $conn_id, $blobidarray);
if (! $res_id) {
... error ...
}
// free result id
ifx_free_result($res_id);
ifx_prepare
ifx_prepare -- Prepare an SQL-statement for execution
Description
int ifx_prepare(string query, int conn_id, int [cursor_def], mixed blobidarray);
Returns a integer result_id for use by ifx_do(). Sets affected_rows for retrieval by the ifx_affected_rows() function.
Prepares query on connection conn_id. For "select-type" queries a cursor is declared and opened. The optional cursor_type parameter allows you to make this a "scroll" and/or "hold" cursor. It's a mask and can be either IFX_SCROLL, IFX_HOLD, or both or'ed together.
For either query type the estimated number of affected rows is saved for retrieval by ifx_affected_rows().
If you have BLOB (BYTE or TEXT) columns in the query, you can add a blobidarray parameter containing the corresponding "blob ids", and you should replace those columns with a "?" in the query text.
If the contents of the TEXT (or BYTE) column allow it, you can also use "ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)". This allows you to treat TEXT (or BYTE) columns just as if they were ordinary (but long) VARCHAR columns for select queries, and you don't need to bother with blob id's.
With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default situation), select queries will return BLOB columns as blob id's (integer value). You can get the value of the blob as a string or file with the blob functions (see below).
See also: ifx_do().
ifx_do
ifx_do -- Execute a previously prepared SQL-statement
Description
int ifx_do(int result_id);
Returns TRUE on success, FALSE on error.
Executes a previously prepared query or opens a cursor for it.
Does NOT free result_id on error.
Also sets the real number of ifx_affected_rows() for non-select statements for retrieval by ifx_affected_rows()
See also: ifx_prepare(). There is a example.
ifx_error
ifx_error -- Returns error code of last Informix call
Description
string ifx_error(void);
The Informix error codes (SQLSTATE & SQLCODE) formatted as follows :
x [SQLSTATE = aa bbb SQLCODE=cccc]
where x = space : no error
E : error
N : no more data
W : warning
? : undefined
If the "x" character is anything other than space, SQLSTATE and SQLCODE describe the error in more detail.
See the Informix manual for the description of SQLSTATE and SQLCODE
Returns in a string one character describing the general results of a statement and both SQLSTATE and SQLCODE associated with the most recent SQL statement executed. The format of the string is "(char) [SQLSTATE=(two digits) (three digits) SQLCODE=(one digit)]". The first character can be ' ' (space) (success), 'W' (the statement caused some warning), 'E' (an error happened when executing the statement) or 'N' (the statement didn't return any data).
See also: ifx_errormsg()
ifx_errormsg
ifx_errormsg -- Returns error message of last Informix call
Description
string ifx_errormsg(int [errorcode]);
Returns the Informix error message associated with the most recent Informix error, or, when the optional "errorcode" param is present, the error message corresponding to "errorcode".
See also: ifx_error()
printf("%s\n<br>", ifx_errormsg(-201));
ifx_affected_rows
ifx_affected_rows -- Get number of rows affected by a query
Description
int ifx_affected_rows(int result_id);
result_id is a valid result id returned by ifx_query() or ifx_prepare().
Returns the number of rows affected by a query associated with result_id.
For inserts, updates and deletes the number is the real number (sqlerrd[2]) of affected rows. For selects it is an estimate (sqlerrd[0]). Don't rely on it.
Useful after ifx_prepare() to limit queries to reasonable result sets.
See also: ifx_num_rows()
Example 1. Informix affected rows
$rid = ifx_prepare ("select * from emp where name like " . $name, $connid);
if (! $rid) {
... error ...
}
$rowcount = ifx_affected_rows ($rid);
if ($rowcount > 1000) {
printf ("Too many rows in result set (%d)\n<br>", $rowcount);
die ("Please restrict your query<br>\n");
}
ifx_fetch_row
ifx_fetch_row -- Get row as enumerated array
Description
array ifx_fetch_row(int result_id, mixed [position] );
Returns an associative array that corresponds to the fetched row, or false if there are no more rows.
Blob columns are returned as integer blob id values for use in ifx_get_blob() unless you have used ifx_textasvarchar(1) or ifx_byteasvarchar(1), in which case blobs are returned as string values. Returns FALSE on error
result_id is a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).
[position] is an optional parameter for a "fetch" operation on "scroll" cursors: "NEXT", "PREVIOUS", "CURRENT", "FIRST", "LAST" or a number. If you specify a number, an "absolute" row fetch is executed. This parameter is optional, and only valid for scrollcursors.
ifx_fetch_row() fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0.
Subsequent call to ifx_fetch_row() would return the next row in the result set, or false if there are no more rows.
Example 1. Informix fetch rows
$rid = ifx_prepare ("select * from emp where name like " . $name,
$connid, IFX_SCROLL);
if (! $rid) {
... error ...
}
$rowcount = ifx_affected_rows($rid);
if ($rowcount > 1000) {
printf ("Too many rows in result set (%d)\n<br>", $rowcount);
die ("Please restrict your query<br>\n");
}
if (! ifx_do ($rid)) {
... error ...
}
$row = ifx_fetch_row ($rid, "NEXT");
while (is_array($row)) {
for(reset($row); $fieldname=key($row); next($row)) {
$fieldvalue = $row[$fieldname];
printf ("%s = %s,", $fieldname, $fieldvalue);
}
printf("\n<br>");
$row = ifx_fetch_row ($rid, "NEXT");
}
ifx_free_result ($rid);
ifx_htmltbl_result
ifx_htmltbl_result -- Formats all rows of a query into a HTML table
Description
int ifx_htmltbl_result(int result_id, string [html_table_options]);
Returns the number of rows fetched or FALSE on error.
Formats all rows of the result_id query into a html table. The optional second argument is a string of <table> tag options
Example 1. Informix results as HTML table
$rid = ifx_prepare ("select * from emp where name like " . $name,
$connid, IFX_SCROLL);
if (! $rid) {
... error ...
}
$rowcount = ifx_affected_rows ($rid);
if ($rowcount > 1000) {
printf ("Too many rows in result set (%d)\n<br>", $rowcount);
die ("Please restrict your query<br>\n");
}
if (! ifx_do($rid) {
... error ...
}
ifx_htmltbl_result ($rid, "border=\"2\"");
ifx_free_result($rid);
ifx_fieldtypes
ifx_fieldtypes -- List of Informix SQL fields
Description
array ifx_fieldtypes(int result_id);
Returns an associative array with fieldnames as key and the SQL fieldtypes as data for query with result_id. Returns FALSE on error.
Example 1. Fielnames and SQL fieldtypes
$types = ifx_fieldtypes ($resultid);
if (! isset ($types)) {
... error ...
}
for ($i = 0; $i < count($types); $i++) {
$fname = key($types);
printf("%s :\t type = %s\n", $fname, $types[$fname]);
next($types);
}
ifx_fieldproperties
ifx_fieldproperties -- List of SQL fieldproperties
Description
array ifx_fieldproperties(int result_id);
Returns an associative array with fieldnames as key and the SQL fieldproperties as data for a query with result_id. Returns FALSE on error.
Returns the Informix SQL fieldproperies of every field in the query as an associative array. Properties are encoded as: "SQLTYPE;length;precision;scale;ISNULLABLE" where SQLTYPE = the Informix type like "SQLVCHAR" etc. and ISNULLABLE = "Y" or "N".
Example 1. Informix SQL fieldproperties
$properties = ifx_fieldtypes ($resultid);
if (! isset($properties)) {
... error ...
}
for ($i = 0; $i < count($properties); $i++) {
$fname = key ($properties);
printf ("%s:\t type = %s\n", $fname, $properties[$fname]);
next ($properties);
}
ifx_num_fields
ifx_num_fields -- Returns the number of columns in the query
Description
int ifx_num_fields(int result_id);
Returns the number of columns in query for result_id or FALSE on error
After preparing or executing a query, this call gives you the number of columns in the query.
ifx_num_rows
ifx_num_rows -- Count the rows already fetched a query
Description
int ifx_num_rows(int result_id);
Gives the number of rows fetched so far for a query with result_id after a ifx_query() or ifx_do() query.
ifx_free_result
ifx_free_result -- Releases resources for the query
Description
int ifx_free_result(int result_id);
Releases resources for the query associated with result_id. Returns FALSE on error.
ifx_create_char
ifx_create_char -- Creates an char object
Description
int ifx_create_char(string param);
Creates an char object. param should be the char content.
ifx_free_char
ifx_free_char -- Deletes the char object
Description
int ifx_free_char(int bid);
Deletes the charobject for the given char object-id bid. Returns FALSE on error otherwise TRUE.
ifx_update_char
ifx_update_char -- Updates the content of the char object
Description
int ifx_update_char(int bid, string content);
Updates the content of the char object for the given char object bid. content is a string with new data. Returns FALSE on error otherwise TRUE.
ifx_get_char
ifx_get_char -- Return the content of the char object
Description
int ifx_get_char(int bid);
Returns the content of the char object for the given char object-id bid.
ifx_create_blob
ifx_create_blob -- Creates an blob object
Description
int ifx_create_blob(int type, int mode, string param);
Creates an blob object.
type: 1 = TEXT, 0 = BYTE
mode: 0 = blob-object holds the content in memory, 1 = blob-object holds the content in file.
param: if mode = 0: pointer to the content, if mode = 1: pointer to the filestring.
Return FALSE on error, otherwise the new blob object-id.
ifx_copy_blob
ifx_copy_blob -- Duplicates the given blob object
Description
int ifx_copy_blob(int bid);
Duplicates the given blob object. bid is the ID of the blob object.
Returns FALSE on error otherwise the new blob object-id.
ifx_free_blob
ifx_free_blob -- Deletes the blob object
Description
int ifx_free_blob(int bid);
Deletes the blobobject for the given blob object-id bid. Returns FALSE on error otherwise TRUE.
ifx_get_blob
ifx_get_blob -- Return the content of a blob object
Description
int ifx_get_blob(int bid);
Returns the content of the blob object for the given blob object-id bid.
ifx_update_blob
ifx_update_blob -- Updates the content of the blob object
Description
ifx_update_blob(int bid, string content);
Updates the content of the blob object for the given blob object bid. content is a string with new data. Returns FALSE on error otherwise TRUE.
ifx_blobinfile_mode
ifx_blobinfile_mode -- Set the default blob mode for all select queries
Description
void ifx_blobinfile_mode(int mode);
Set the default blob mode for all select queries. Mode "0" means save Byte-Blobs in memory, and mode "1" means save Byte-Blobs in a file.
ifx_textasvarchar
ifx_textasvarchar -- Set the default text mode
Description
void ifx_textasvarchar(int mode);
Sets the default text mode for all select-queries. Mode "0" will return a blob id, and mode "1" will return a varchar with text content.
ifx_byteasvarchar
ifx_byteasvarchar -- Set the default byte mode
Description
void ifx_byteasvarchar(int mode);
Sets the default byte mode for all select-queries. Mode "0" will return a blob id, and mode "1" will return a varchar with text content.
ifx_nullformat
ifx_nullformat -- Sets the default return value on a fetch row
Description
void ifx_nullformat(int mode);
Sets the default return value of a NULL-value on a fetch row. Mode "0" returns "", and mode "1" returns "NULL".
ifxus_create_slob
ifxus_create_slob -- Creates an slob object and opens it
Description
int ifxus_create_slob(int mode);
Creates an slob object and opens it. Modes: 1 = LO_RDONLY, 2 = LO_WRONLY, 4 = LO_APPEND, 8 = LO_RDWR, 16 = LO_BUFFER, 32 = LO_NOBUFFER -> or-mask. You can also use constants named IFX_LO_RDONLY, IFX_LO_WRONLY etc. Return FALSE on error otherwise the new slob object-id.
ifx_free_slob
ifx_free_slob -- Deletes the slob object
Description
int ifxus_free_slob(int bid);
Deletes the slob object. bid is the Id of the slob object. Returns FALSE on error otherwise TRUE.
ifxus_close_slob
ifxus_close_slob -- Deletes the slob object
Description
int ifxus_close_slob(int bid);
Deletes the slob object on the given slob object-id bid. Return FALSE on error otherwise TRUE.
ifxus_open_slob
ifxus_open_slob -- Opens an slob object
Description
int ifxus_open_slob(long bid, int mode);
Opens an slob object. bid should be an existing slob id. Modes: 1 = LO_RDONLY, 2 = LO_WRONLY, 4 = LO_APPEND, 8 = LO_RDWR, 16 = LO_BUFFER, 32 = LO_NOBUFFER -> or-mask. Returns FALSE on error otherwise the new slob object-id.
ifxus_tell_slob
ifxus_tell_slob -- Returns the current file or seek position
Description
int ifxus_tell_slob(long bid);
Returns the current file or seek position of an open slob object bid should be an existing slob id. Return FALSE on error otherwise the seek position.
ifxus_seek_slob
ifxus_seek_slob -- Sets the current file or seek position
Description
int ifxus_seek_blob(long bid, int mode, long offset);
Sets the current file or seek position of an open slob object. bid should be an existing slob id. Modes: 0 = LO_SEEK_SET, 1 = LO_SEEK_CUR, 2 = LO_SEEK_END and offset is an byte offset. Return FALSE on error otherwise the seek position.
ifxus_read_slob
ifxus_read_slob -- Reads nbytes of the slob object
Description
int ifxus_read_slob(long bid, long nbytes);
Reads nbytes of the slob object. bid is a existing slob id and nbytes is the number of bytes zu read. Return FALSE on error otherwise the string.
ifxus_write_slob
ifxus_write_slob -- Writes a string into the slob object
Description
int ifxus_write_slob(long bid, string content);
Writes a string into the slob object. bid is a existing slob id and content the content to write. Return FALSE on error otherwise bytes written.
XX. InterBase Functions
Table of Contents
ibase_connect
ibase_pconnect
ibase_close
ibase_query
ibase_fetch_row
ibase_free_result
ibase_prepare
ibase_bind
ibase_execute
ibase_free_query
ibase_timefmt
ibase_connect
ibase_connect --
Description
ibase_connect( );
ibase_pconnect
ibase_pconnect --
Description
ibase_pconnect( );
ibase_close
ibase_close --
Description
ibase_close( );
ibase_query
ibase_query --
Description
ibase_query( );
ibase_fetch_row
ibase_fetch_row --
Description
ibase_fetch_row( );
ibase_free_result
ibase_free_result --
Description
ibase_free_result( );
ibase_prepare
ibase_prepare --
Description
ibase_prepare( );
ibase_bind
ibase_bind --
Description
ibase_bind( );
ibase_execute
ibase_execute --
Description
ibase_execute( );
ibase_free_query
ibase_free_query --
Description
ibase_free_query( );
ibase_timefmt
ibase_timefmt --
Description
ibase_timefmt( );
XXI. LDAP Functions
Table of Contents
ldap_add
ldap_bind
ldap_close
ldap_connect
ldap_count_entries
ldap_delete
ldap_dn2ufn
ldap_explode_dn
ldap_first_attribute
ldap_first_entry
ldap_free_result
ldap_get_attributes
ldap_get_dn
ldap_get_entries
ldap_get_values
ldap_list
ldap_modify
ldap_next_attribute
ldap_next_entry
ldap_read
ldap_search
ldap_unbind
Introduction to LDAP
LDAP is the Lightweight Directory Access Protocol, and is a protocol used to access "Directory Servers". The Directory is a special kind of database that holds information in a tree structure.
The concept is similar to your hard disk directory structure, except that in this context, the root directory is "The world" and the first level subdirectories are "countries". Lower levels of the directory structure contain entries for companies, organisations or places, while yet lower still we find directory entries for people, and perhaps equipment or documents.
To refer to a file in a subdirectory on your hard disk, you might use something like
/usr/local/myapp/docs
The forwards slash marks each division in the reference, and the sequence is read from left to right.
The equivalent to the fully qualified file reference in LDAP is the "distinguished name", referred to simply as "dn". An example dn might be.
cn=John Smith,ou=Accounts,o=My Company,c=US
The comma marks each division in the reference, and the sequence is read from right to left. You would read this dn as ..
country = US
organization = My Company
organizationalUnit = Accounts
commonName = John Smith
In the same way as there are no hard rules about how you organise the directory structure of a hard disk, a directory server manager can set up any structure that is meaningful for the purpose. However, there are some conventions that are used. The message is that you can not write code to access a directory server unless you know something about its structure, any more than you can use a database without some knowledge of what is available.
--------------------------------------------------------------------------------
Complete code example
Retrieve information for all entries where the surname starts with "S" from a directory server, displaying an extract with name and email address.
Example 1. LDAP search example
<?php
// basic sequence with LDAP is connect, bind, search, interpret search
// result, close connection
echo "<h3>LDAP query test</h3>";
echo "Connecting ...";
$ds=ldap_connect("localhost"); // must be a valid LDAP server!
echo "connect result is ".$ds."<p>";
if ($ds) {
echo "Binding ...";
$r=ldap_bind($ds); // this is an "anonymous" bind, typically
// read-only access echo "Bind result is
echo "Bind result is ".$r."<p>";
echo "Searching for (sn=S*) ...";
// Search surname entry
$sr=ldap_search($ds,"o=My Company, c=US", "sn=S*");
echo "Search result is ".$sr."<p>";
echo "Number of entires returned is ".ldap_count_entries($ds,$sr)."<p>";
echo "Getting entries ...<p>";
$info = ldap_get_entries($ds, $sr);
echo "Data for ".$info["count"]." items returned:<p>";
for ($i=0; $i<$info["count"]; $i++) {
echo "dn is: ". $info[$i]["dn"] ."<br>";
echo "first cn entry is: ". $info[$i]["cn"][0] ."<br>";
echo "first email entry is: ". $info[$i]["mail"][0] ."<p>";
}
echo "Closing connection";
ldap_close($ds);
} else {
echo "<h4>Unable to connect to LDAP server</h4>";
}
?>
--------------------------------------------------------------------------------
Using the PHP LDAP calls
You will need to get and compile LDAP client libraries from either the University of Michigan ldap-3.3 package or the Netscape Directory SDK. You will also need to recompile PHP with LDAP support enabled before PHP's LDAP calls will work.
Before you can use the LDAP calls you will need to know ..
The name or address of the directory server you will use
The "base dn" of the server (the part of the world directory that is held on this server, which could be "o=My Company,c=US")
Whether you need a password to access the server (many servers will provide read access for an "anonymous bind" but require a password for anything else)
The typical sequence of LDAP calls you will make in an application will follow this pattern:
ldap_connect() // establish connection to server
|
ldap_bind() // anonymous or authenticated "login"
|
do something like search or update the directory
and display the results
|
ldap_close() // "logout"
--------------------------------------------------------------------------------
More Information
Lots of information about LDAP can be found at
Netscape
University of Michigan
OpenLDAP Project
LDAP World
The Netscape SDK contains a helpful Programmer's Guide in .html format.
ldap_add
ldap_add -- Add entries to LDAP directory
Description
int ldap_add(int link_identifier, string dn, array entry);
returns true on success and false on error.
The ldap_add() function is used to add entries in the LDAP directory. The DN of the entry to be added is specified by dn. Array entry specifies the information about the entry. The values in the entries are indexed by individual attributes. In case of multiple values for an attribute, they are indexed using integers starting with 0.
entry["attribute1"] = value
entry["attribute2"][0] = value1
entry["attribute2"][1] = value2
Example 1. Complete example with authenticated bind
<?php
$ds=ldap_connect("localhost"); // assuming the LDAP server is on this host
if ($ds) {
// bind with appropriate dn to give update access
$r=ldap_bind($ds,"cn=root, o=My Company, c=US", "secret");
// prepare data
$info["cn"]="John Jones";
$info["sn"]="Jones";
$info["mail"]="jonj@here.and.now";
$info["objectclass"]="person";
// add data to directory
$r=ldap_add($ds, "cn=John Jones, o=My Company, c=US", $info);
ldap_close($ds);
} else {
echo "Unable to connect to LDAP server";
}
?>
ldap_bind
ldap_bind -- Bind to LDAP directory
Description
int ldap_bind(int link_identifier, string bind_rdn, string bind_password);
Binds to the LDAP directory with specified RDN and password. Returns true on success and false on error.
ldap_bind() does a bind operation on the directory. bind_rdn and bind_password are optional. If not specified, anonymous bind is attempted.
ldap_close
ldap_close -- Close link to LDAP server
Description
int ldap_close(int link_identifier);
Returns true on success, false on error.
ldap_close() closes the link to the LDAP server that's associated with the specified link_identifier.
This call is internally identical to ldap_unbind(). The LDAP API uses the call ldap_unbind(), so perhaps you should use this in preference to ldap_close().
ldap_connect
ldap_connect -- Connect to an LDAP server
Description
int ldap_connect(string hostname, int port);
Returns a positive LDAP link identifier on success, or false on error.
ldap_connect() establishes a connection to a LDAP server on a specified hostname and port. Both the arguments are optional. If no arguments are specified then the link identifier of the already opened link will be returned. If only hostname is specified, then the port defaults to 389.
ldap_count_entries
ldap_count_entries -- Count the number of entries in a search
Description
int ldap_count_entries(int link_identifier, int result_identifier);
Returns number of entries in the result or false on error.
ldap_count_entries() returns the number of entries stored in the result of previous search operations. result_identifier identifies the internal ldap result.
ldap_delete
ldap_delete -- Delete an entry from a directory
Description
int ldap_delete(int link_identifier, string dn);
Returns true on success and false on error.
ldap_delete() function delete a particular entry in LDAP directory specified by dn.
ldap_dn2ufn
ldap_dn2ufn -- Convert DN to User Friendly Naming format
Description
string ldap_dn2ufn(string dn);
ldap_dn2ufn() function is used to turn a DN into a more user-friendly form, stripping off type names.
ldap_explode_dn
ldap_explode_dn -- Splits DN into its component parts
Description
array ldap_explode_dn(string dn, int with_attrib);
ldap_explode_dn() function is used to split the a DN returned by ldap_get_dn() and breaks it up into its component parts. Each part is known as Relative Distinguished Name, or RDN. ldap_explode_dn() returns an array of all those components. with_attrib is used to request if the RDNs are returned with only values or their attributes as well. To get RDNs with the attributes (i.e. in attribute=value format) set with_attrib to 1 and to get only values set it to 0.
ldap_first_attribute
ldap_first_attribute -- Return first attribute
Description
string ldap_first_attribute(int link_identifier, int result_entry_identifier, int ber_identifier);
Returns the first attribute in the entry on success and false on error.
Similar to reading entries, attributes are also read one by one from a particular entry. ldap_first_attribute() returns the first attribute in the entry pointed by the entry identifier. Remaining attributes are retrieved by calling ldap_next_attribute() successively. ber_identifier is the identifier to internal memory location pointer. It is passed by reference. The same ber_identifier is passed to the ldap_next_attribute() function, which modifies that pointer.
see also ldap_get_attributes()
ldap_first_entry
ldap_first_entry -- Return first result id
Description
int ldap_first_entry(int link_identifier, int result_identifier);
Returns the result entry identifier for the first entry on success and false on error.
Entries in the LDAP result are read sequentially using the ldap_first_entry() and ldap_next_entry() functions. ldap_first_entry() returns the entry identifier for first entry in the result. This entry identifier is then supplied to lap_next_entry() routine to get successive entries from the result.
see also ldap_get_entries().
ldap_free_result
ldap_free_result -- Free result memory
Description
int ldap_free_result(int result_identifier);
Returns true on success and false on error.
ldap_free_result() frees up the memory allocated internally to store the result and pointed by the result_identifier. All result memory will be automatically freed when the script terminates.
Typically all the memory allocated for the ldap result gets freed at the end of the script. In case the script is making successive searches which return large result sets, ldap_free_result() could be called to keep the runtime memory usage by the script low.
ldap_get_attributes
ldap_get_attributes -- Get attributes from a search result entry
Description
array ldap_get_attributes(int link_identifier, int result_entry_identifier);
Returns a comlete entry information in a multi-dimensional array on success and false on error.
ldap_get_attributes() function is used to simplify reading the attributes and values from an entry in the search result. The return value is a multi-dimensional array of attributes and values.
Having located a specific entry in the directory, you can find out what information is held for that entry by using this call. You would use this call for an application which "browses" directory entries and/or where you do not know the structure of the directory entries. In many applications you will be searching for a specific attribute such as an email address or a surname, and won't care what other data is held.
return_value["count"] = number of attributes in the entry
return_value[0] = first attribute
return_value[n] = nth attribute
return_value["attribute"]["count"] = number of values for attribute
return_value["attribute"][0] = first value of the attribute
return_value["attribute"][i] = ith value of the attribute
Example 1. Show the list of attributes held for a particular directory entry
// $ds is the link identifier for the directory
// $sr is a valid search result from a prior call to
// one of the ldap directory search calls
$entry = ldap_first_entry($ds, $sr);
$attrs = ldap_get_attributes($ds, $entry);
echo $attrs["count"]." attributes held for this entry:<p>";
for ($i=0; $i<$attrs["count"]; $i++)
echo $attrs[$i]."<br>";
see also ldap_first_attribute() and ldap_next_attribute()
ldap_get_dn
ldap_get_dn -- Get the DN of a result entry
Description
string ldap_get_dn(int link_identifier, int result_entry_identifier);
Returns the DN of the result entry and false on error.
ldap_get_dn() function is used to find out the DN of an entry in the result.
ldap_get_entries
ldap_get_entries -- Get all result entries
Description
array ldap_get_entries(int link_identifier, int result_identifier);
Returns a complete result information in a multi-dimenasional array on success and false on error.
ldap_get_entries() function is used to simplify reading multiple entries from the result and then reading the attributes and multiple values. The entire information is returned by one function call in a multi-dimensional array. The structure of the array is as follows.
The attribute index is converted to lowercase. (Attributes are case-insensitive for directory servers, but not when used as array indices)
return_value["count"] = number of entries in the result
return_value[0] : refers to the details of first entry
return_value[i]["dn"] = DN of the ith entry in the result
return_value[i]["count"] = number of attributes in ith entry
return_value[i][j] = jth attribute in the ith entry in the result
return_value[i]["attribute"]["count"] = number of values for
attribute in ith entry
return_value[i]["attribute"][j] = jth value of attribute in ith entry
see also ldap_first_entry() and ldap_next_entry()
ldap_get_values
ldap_get_values -- Get all values from a result entry
