Parameter Formats

The descriptions that follow provide details on the meaning and formatting of many key parameters used throughout this manual.

The hostName is the host name or IP address, such as "dns.4d.com" or "204.118.90.2". Host names are resolved through a domain name system. The default and secondary domain name systems are typically set within the Control Panel of the installed TCP/IP driver. Any 4D Internet command requiring a hostName as a parameter will accept its value in either the name ("www.4d.com") or IP address ("204.118.90.2") format. The "name" format is always preferred since it buffers your application from ill effects due to hardware changes at remote sites.

All host names can be resolved via the methods described above to an IP address. Mathematical formulas can then be applied to the IP address to convert the value to a unique long integer number. Commands within the 'Special Functions' section such as NET_NameToAddr and NET_AddrToName automate this conversion process. This LongInt value is referred to as the ip_LongInt throughout this documentation. The LongInt value will only be of use in special circumstances by developers doing direct TCP communication. Some developers may also prefer to store the LongInt value of a domain name in order to conserve disk space compared to its string equivalent. However, for compatibility reasons with IPV6, 4D advises developers against using this feature.

The MailAddress is a fully qualified mail specification in the format "user_name@domain_name". Within this document, mailAddress refers to a single e-mail address. Any 4D Internet Commands parameter which can take more than one address will specifically state addressList. If a parameter has mailAddress as its only type, it can take one and only one mail address. The format of the mailAddress should be a full reference containing both the user name and domain name:

• "Felix Unger" <felix@pristine.com>
• oscar@slobs.com (Oscar Madison)

An addressList contains one or more e-mail addresses in the format of mailAddress, each delimited by a comma or carriage return. Carriage return delimiting is useful when providing users with a text field to enter or paste a number of addresses. The following three examples would each generate an acceptable $AddressList value:

The localPath is the location of a file or directory on the users machine (Mac or Windows). On a Macintosh, colons delimit items within folders. For example, the file "My Report" in the "Reports" folder on the hard drive titled "My Hard Drive" would have a pathname of "My Hard Drive:Reports:My Report". A directory specification on a Macintosh must end with a colon character. For example, if you wanted to place a new report in the same folder as the above example, you would refer to the directory as "My Hard Drive:Reports:". The decision to reference a File or Directory name is based on the context called for by the command. A similar format is used under the Windows environment, except a backward slash "\" is used instead of the colon.

Note: With the FTP protocol, 4D internet commands do not allow you to work with files whose names are longer than 31 characters (see File Transfer, Overview).

The hostPath is the location of a file or directory on a computer running under the Unix operating system. In the Unix environment, directories are separated with slashes ("/"). For example, the file "report.txt" in the "reports" directory in the "4D" directory would be specified as "/4D/reports/report.txt". A directory pathname must end with a "/" character. Note that a full pathname begins with a "/" which represents the root of the volume.

Throughout each section of 4D Internet Commands, references are made to an "ID" number in most of the commands. Each set of communication functions will establish their own "session" represented by a Long Integer "ID" number. Subsequent commands related to the open session will use this value to direct their effects down the proper channel.

The "ID" numbers obtained in each section (SMTP, POP3, IMAP, FTP, TCP, UDP) may not be passed as values to different sections. However, for greater flexibility, 4D Internet commands let you pass a POP3, IMAP or FTP connection reference directly to low-level TCP commands and vice versa. For more information, please refer to the Low Level Routines, Overview section.

All 4D Internet Commands (with the exception of IT_ErrorText and IT_Version) return an integer value as the result of the function. This integer contains any error number that the command needs to convey back to the 4D database. If a command is successful, a zero will be returned. Otherwise, an error code is returned. For more information about 4D Internet Commands error codes, please refer to Appendix C, 4D Internet Commands Error Codes.