This chapter is for application programmers. It describes the TCPware FTP library routines.
The TCPware FTP library routines provide a programming interface to the FTP protocol. Use the FTP library routines in your own applications to provide FTP capabilities.
The following routines are included in the library:
|
FTP_ACCOUNT |
Specifies the user account on the remote host |
|
FTP_ALLOCATE_CCB |
Allocates a connection control block (CCB) |
|
FTP_APPEND_FILE |
Appends a file to a remote file |
|
FTP_AUTH |
Requests protected authentication. |
|
FTP_CCC |
Requests that the command channel be clear text. |
|
FTP_CHECK_FEATURES |
Sends the FEAT command to the FTP server and builds a bit mask of supported FTP optional features. |
|
FTP_CLOSE_CONNECTION |
Closes the connection to the remote FTP server |
|
FTP_CREATE_DIRECTORY |
Creates a directory on the remote host |
|
FTP_DEALLOCATE_CCB |
Deallocates a CCB |
|
FTP_DELETE_DIRECTORY |
Deletes a directory on the remote host |
|
FTP_DELETE_FILE |
Deletes a file on the remote host |
|
FTP_GET_CCB |
Gets information from a CCB field |
|
FTP_GET_FILE |
Copies a file from the remote host |
|
FTP_GET_LIST |
Gets file listing on the remote host |
|
FTP_GET_NAME_LIST |
Gets a filename listing on the remote host |
|
FTP_LOGIN_USER |
Authorizes the user on the remote host |
|
FTP_OPEN_CONNECTION |
Opens an FTP connection |
|
FTP_PASSWORD |
Specifies the user password on the remote host |
|
FTP_PBSZ |
Specifies the protection buffer size. |
|
FTP_PRINT_DIRECTORY |
Returns the current directory on the remote host |
|
FTP_PROT |
Specifies the protection level to use for transfers |
|
FTP_PUT_FILE |
Copies a file to the remote host |
|
FTP_QUOTE |
Sends an FTP command to the remote host |
|
FTP_RENAME_FILE |
Renames a file on the remote host |
|
FTP_SET_DIRECTORY |
Sets the remote directory |
|
FTP_SET_DEBUG |
Sets the debugging mode |
|
FTP_SET_PASV |
Sets passive mode transfers |
|
FTP_SET_STRU |
Specifies the file structure |
|
FTP_SET_TYPE |
Specifies the data representation type |
|
FTP_USER |
Specifies the user on the remote host |
These routines allow you to establish and maintain FTP connections with remote hosts that support the FTP protocol.
The TCPware FTP library routines follow the standard OpenVMS conventions for modular library routines. See the OpenVMS documentation on calling modular libraries for more information.
Because TCPware FTP library routines use asynchronous system traps (ASTs), application programs must not run with ASTs disabled for long periods of time. Also, you should not call TCPware FTP library routines at the AST level.
The TCPware FTP library routines are in the TCPWARE_FTPLIB_SHR.EXE shareable library. The symbolic definitions for the various CCB fields and other parameters are in the TCPWARE_INCLUDE:FTPDEF.H header file. While this file is written for C language, it is very easy to convert to other OpenVMS languages.
The FTP Client sample program is provided in TCPWARE_COMMON:[TCPWARE.EXAMPLES]FTPSAMPLE.C.
To build using DEC C, enter:
$ CC/DECC/PREFIX=ALL FTPSAMPLE.C
$ LINK FTPSAMPLE,
SYS$INPUT/OPTIONS –
_$ SYS$SHARE:TCPWARE_FTPLIB_SHR/SHARE -
_$ SYS$SHARE:TCPWARE_SOCKLIB_SHR/SHARE
To build using VAX C, enter:
$ CC/VAXC/PREFIX=ALL
FTPSAMPLE.C
$ LINK
FTPSAMPLE, SYS$INPUT/OPTIONS -
_$ SYS$SHARE:TCPWARE_FTPLIB_SHR/SHARE
-
_$ SYS$SHARE:TCPWARE_SOCKLIB_SHR/SHARE
-
_$ SYS$SHARE:VAXCRTL.EXE/SHARE
The connection control block (CCB) contains all the information required to establish and maintain an FTP connection. Each open connection requires a CCB.
The storage space for the CCB is allocated dynamically. Therefore, the number of simultaneous connections is limited only by your process resources. You can reuse a CCB. You can close one connection and open a new one using the same CCB.
Gain access to the CCB fields using the FTP_GET_CCB library routine as described in Library Routines.
The below table lists CCB fields and their uses:
|
CCB Fields |
CCB Uses |
|
FTP_CCB_DC_CHAN |
Channel for the FTP data connection (unsigned word) |
|
FTP_CCB_DC_PN |
Port number of the data connection (unsigned word) |
|
FTP_CCB_FEATURE_MASK |
Longword bit mask of server features reported by the response to the FTP FEAT command sent by the CHECK_FEATURES subroutine |
|
FTP_CCB_FILENAME |
Name of the file causing the transfer error (character string descriptor) |
|
FTP_CCB_FOR_IA |
IP address of the remote host (unsigned longword) |
|
FTP_CCB_FOR_PN |
Remote port number of the control connection (unsigned word) |
|
FTP_CCB_FX_TYPE |
Data representation type (character string descriptor with a maximum length of 2); see the FTP_SET_TYPE routine for the possible values |
|
FTP_CCB_LOC_IA |
IP address of the local host (unsigned longword) |
|
FTP_CCB_LOC_PN |
Local port number of the control connection (unsigned word) |
|
FTP_CCB_LOGGED_IN |
Login status (Boolean); true if the user is successfully logged in on the remote host |
|
FTP_CCB_NETCHAN |
Channel for the FTP control connection (unsigned word) |
|
FTP_CCB_NODENAME |
Node name of the remote host (character string descriptor with a maximum length of 128) |
|
FTP_CCB_OPENED |
Connection status (Boolean); true if control connection is successfully opened to the remote host |
|
FTP_CCB_PASSWORD |
User password on the remote host (character string descriptor with a maximum length of 64 characters) |
|
FTP_CCB_PASV |
Boolean that indicates whether passive mode is enabled (TRUE) or disabled (FALSE). |
|
FTP_CCB_RPLCOD |
Server reply code (longword) |
|
FTP_CCB_RPLLEN |
Length of the server reply message (longword) |
|
FTP_CCB_RPLTXT |
Reply text received from the server (character string descriptor with a maximum length of 512 characters) |
|
FTP_CCB_STAT_BYTES |
Number of bytes transferred (longword) |
|
FTP_CCB_STAT_SECONDS |
Seconds required for the transfer (double floating point) |
|
FTP_CCB_STATUS |
Completion status (unsigned longword) |
|
FTP_CCB_STRU |
File structure (character string descriptor); see the FTP_SET_STRU routine for the possible values |
|
FTP_CCB_USERNAME |
Username on the remote host (character string descriptor with a maximum length of 64 characters) |
The FTP_APPEND_FILE, FTP_GET_FILE, and FTP_PUT_FILE library routines described in Library Routines have two optional arguments: mode and record-size. These options provide finer control in transferring OpenVMS files.
Using the mode argument causes the transfer mode set by FTP_SET_TYPE and FTP_SET_STRU to be ignored. The lower word of the mode longword specifies the primary transfer mode. The following symbols define the primary transfer mode:
|
MODE_C_ASCII |
Transfers the file in ASCII format |
|
MODE_C_IMAGE |
Transfers the file in IMAGE mode |
|
MODE_C_BINARY |
Transfers .OBJ, .STB, .BIN, and .LDA files in BINARY format |
|
MODE_C_BLOCK |
Transfers STREAM, STREAM_LF, STREAM_CR and UNDEFINED files in BLOCK mode |
The higher word of the mode longword defines optional transfer modes. The following symbols define the optional transfer modes:
|
MODE_M_FCC |
Combined with MODE_C_ASCII, transfers the ASCII file with FORTRAN carriage control. |
|
MODE_M_APPEND |
Appends the source to a destination file. (Not supported by all servers.) |
|
MODE_M_VARIABLE |
Combined with MODE_C_IMAGE, transfers an image file in variable length recode mode, except that all records are the same length. (Applies to local output image files only.) |
|
MODE_M_RECORD |
Transfers the file using STRU_R so as to communicate the record structure during the copy. (Not supported by all servers.) |
|
MODE_M_RESTART |
When transferring the file in STREAM mode performs a restart from where the transfer stopped based upon file size. Requires support of the feature and the CHECK_FEATURES routine to be called beforehand. |
|
MODE_M_VMS |
Transfers the file in VMS file mode.
Using MODE_M_VMS allows you to transfer any type of RMS file between OpenVMS systems. Note that if specifying this flag, all other flags are ignored. |
To access TCPware error status codes, such as TCPWARE_REJECTED, define them in the code as follows:
globalvalue TCPWARE_REJECTED;
Then LINK with the definitions of TCPware error messages using the link option:
TCPWARE:SOCKLIB.OLB/INCLUDE=TCPWARE_MSGPTR
For example, the following code checks if the status returned by FTP_PUT_FILE is TCPWARE_REJECTED and takes the appropriate action:
globalvalue TCPWARE_REJECTED;
...
status = FTP_PUT_FILE(...);
if (status == TCPWARE_REJECTED)
{
do something;
return status;
}
This section describes each of the TCPware FTP library routines. Each function argument is described using standard OpenVMS notation for procedure arguments.
All scalar and buffer arguments are passed by reference. Strings are passed by descriptor. All function arguments must be specified, although some optional arguments may be omitted by passing a 0 (by value).
Each TCPware FTP library routine returns an unsigned longword condition value in R0. The standard system service return codes defined in the $SSDEF macro are used. Gain access to the TCPware error statuses (those beginning with TCPWARE) by global value.
These routines are included in the TCPWARE_FTPLIB_SHR.EXE shareable library.
Specifies the user account on the remote host.
FTP_ACCOUNT(u_long ccb, char *account);
ccb
Identifies the CCB with the active connection.
account
Name of the user account on the remote host.
This routine sends the FTP ACCT command to specify the name of the account on the remote host.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_NEEDACCT |
Server requires an account for login |
|
TCPWARE_LOGINFAIL |
Login attempt failed |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Allocates a connection control block (CCB).
FTP_ALLOCATE_CCB(u_long *ccb);
ccb
Returns a pointer to the new CCB.
This routine allocates a new CCB, initializes the resources, and returns a pointer to it. A CCB must be allocated before all the subsequent calls to the TCPware FTP library routines.
Any condition value returned by LIB$GET_VM and LIB$GET_EF can be returned.
#include <descrip.h>
#include <ssdef.h>
#include "ftpdef.h"
main ()
{
$DESCRIPTOR(host, "ds.internic.net");
$DESCRIPTOR(user, "anonymous");
$DESCRIPTOR(pswd, "your-name@your-site");
$DESCRIPTOR(dir, "rfc");
$DESCRIPTOR(file, "rfc-index.txt");
long ccb, status;
long debug = DEBUG_REPLY;
status = SS$_NORMAL;
ftp_allocate_ccb(&ccb);
.
.
.
return (status);
}
Appends a file to a remote file.
FTP_APPEND_FILE(u_long ccb, char *source, [char *destination], [long mode], [long *record-size]);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
source
Source file on the local host.
destination
Destination file on the remote host. If omitted, the source filename and extensions are used.
mode
Transfer mode. See the Transferring Files section for the list of available transfer mode codes.
|
Note: Using mode causes the transfer mode set by FTP_SET_TYPE and FTP_SET_STRU to be ignored.
|
record-size
Record size of the local output file when transferring in IMAGE mode.
This routine sends the APPE command to append the local file to the file on the remote host.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_OPENIN |
Error opening a file for input |
|
TCPWARE_OPENDATA |
Failed to open data connection |
|
TCPWARE_SETPORT |
Failed to set up data connection |
|
TCPWARE_FILRDERR |
Error reading from or sending a file |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Specifies the authentication/security mechanism to be used as per RFC 2228 and RFC 4217. Currently only TLS is supported.
FTP_AUTH(u_long ccb, char *mechanism);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
mechanism
Specifies the authentication/security mechanism to use. Currently only TLS is supported.
This routine sends an FTP AUTH command to the FTP server. The FTP_AUTH() procedure resets the data transfer parameters to the original state as specified in the RFCs.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
|
TCPWARE_IVREQUEST |
Invalid request |
|
TCPWARE_REQFAIL |
Request failed. |
Specifies that the command channel return to clear text transmission.
FTP_CCC(u_long ccb);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
This routine sends an FTP CCC command to the FTP server.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
Sends the FEAT command to the server and builds the bit mask of supported features.
FTP_CHECK_FEATURES(u_long ccb);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
This routine sends an FTP FEAT command to the FTP server and interprets the response to build a bit mask of supported optional features.
None.
Closes the connection to the remote FTP server if one is open.
FTP_CLOSE_CONNECTION (u_long ccb);
ccb
Identifies the CCB whose active FTP connection is to be closed.
This routine sends an FTP QUIT command to the remote FTP server to close the connection and free up the resources allocated to it.
|
SS$_NORMAL |
Normal successful completion |
status = ftp_get_file(ccb,
&file, 0, 0, 0);
if (!(status & 1))
{
printf("failed to get file %s", file.dsc$a_pointer);
goto error;
}
error:
ftp_close_connection(ccb);
return(status);
Creates a directory on the remote host.
FTP_CREATE_DIRECTORY(u_long ccb, char *directory);
ccb
Identifies the CCB with the active and logged-in connection.
directory
Directory specification on the remote host.
This routine sends an FTP MKD command that creates a specified directory on the remote server. If the pathname is relative, a subdirectory is created under the current remote directory. If the MKD command is rejected, the XMKD command is used.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_CREATEFAIL |
Failed to create the directory |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Deallocates a CCB.
FTP_DEALLOCATE_CCB(u_long *ccb);
ccb
Identifies the CCB you want to deallocate.
This routine deallocates a CCB that is no longer needed. The CCB is deallocated when it is fully closed. An implicit abort is performed on the connection if the CCB is still in use.
The virtual memory and event flag reserved for the CCB by the FTP_ALLOCATE_CCB() routine are freed when this routine is completed.
|
SS$_NORMAL |
Normal successful completion |
status = ftp_get_file(ccb,
&file, 0, 0, 0);
if ((status & 1))
{
printf("failed to get file %s", file.dsc$a_pointer);
goto error;
}
error:
ftp_close_connection(ccb);
error_nocon:
ftp_deallocate_ccb(&ccb);
return(status);
Deletes a directory on the remote host.
FTP_DELETE_DIRECTORY(u_long ccb, char *directory);
ccb
Identifies the CCB with the active and logged-in connection.
directory
Directory to be deleted on the remote host.
This routine sends an FTP RMD command to delete a specified directory on the remote server. If the RMD command is rejected, the XRWD command is used.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_DELETEFAIL |
Failed to delete the remote directory |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Deletes a file on the remote host.
FTP_DELETE_FILE(u_long ccb, char *file);
ccb
Identifies the CCB with the active and logged-in connection.
file
File specification of the file to be deleted on the remote host
This routine sends an FTP DELE command to delete a specified file on the remote server.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_DELETEFAIL |
Failed to delete the remote file |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Gets information from a CCB field.
FTP_GET_CCB(u_long ccb, u_long *field-code, u_long *value, int *length);
ccb
Identifies the CCB from which information is retrieved.
field-code
Code specifying the CCB field information you are requesting.
See Connection Control Block for the valid field codes and their data types. Symbols for these field codes are defined in the TCPWARE_INCLUDE:FTPDEF.H file.
value
Returned value of the specified CCB field. The value argument is the address of a variable that will receive the value of the CCB field. The data type of this variable depends on the field requested in field-code.
length
Returns the resulting length of the value field if the data type of the returned value is STRING.
This routine returns the contents of the specified field from the CCB.
|
SS$_NORMAL |
Normal, successful completion |
|
SS$_BADPARAM |
Bad parameter specified |
Copies a file from a remote host.
FTP_GET_FILE(u_long ccb, char *source, [char *destination], [long *mode], [word *record-size]);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
source
Source file on the remote host.
destination
Destination file on the local host. If omitted, the source filename and extensions are used.
mode
Transfer mode. See Transferring Files for a list of available transfer mode codes.
|
Note: Using mode causes the transfer mode set by FTP_SET_TYPE and FTP_SET_STRU to be ignored.
|
record-size
Record size of the local output file when transferring in IMAGE mode.
This routine sends an FTP RETR command to transfer a remote file to the local host.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_OPENOUT |
Error opening a file for output |
|
TCPWARE_OPENDATA |
Failed to open data connection |
|
TCPWARE_SETPORT |
Failed to set up data connection |
|
TCPWARE_FILWRTERR |
Error writing to or receiving a file |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
$DESCRIPTOR(file,
"rfc-index.txt");
long ccb, status;
status = ftp_get_file(ccb, &file, 0, 0, 0);
if (!(status & 1))
{
printf("failed to get file %s", file.dsc$a_pointer);
goto error;
}
error:
ftp_close_connection(ccb);
return(status);
Gets a file listing on the remote host.
FTP_GET_LIST(u_long ccb, [char *directory], char *output);
ccb
Identifies the CCB with the active and logged-in connection.
directory
Directory specification on the remote host. If omitted, the current remote directory is used.
output
Specifies the local file where the output of the remote directory listing is stored.
This routine sends the FTP LIST command to list a remote directory and stores the output to the local file. The output is in the format of the remote operating system.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_OPENOUT |
Error opening a file for output |
|
TCPWARE_OPENDATA |
Failed to open data connection |
|
TCPWARE_SETPORT |
Failed to set up data connection |
|
TCPWARE_FILWRTERR |
Error writing to or receiving a file |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Gets a filename listing on the remote host.
FTP_GET_NAME_LIST(u_long ccb, [char *directory], char *output);
ccb
Identifies the CCB with the active and logged-in connection.
directory
Directory specification on the remote host. If omitted, the current remote directory is used.
output
Specifies the local file where the output of the remote directory listing is stored.
This routine sends the FTP NAME LIST (NLIST) command to retrieve the name list of the specified remote directory and stores it in the local file. Output is a list of valid file pathnames with each name separated in separate lines. Usually, this output is more suitable for machine processing than the list obtained using FTP_GET_LIST().
See the FTP_GET_LIST() routine.
Authorizes the user on the remote host.
FTP_LOGIN_USER(u_long ccb, char *username, char *password);
ccb
Identifies the CCB of the active network connection.
username
Username on the remote host.
password
Password of the user on the remote host.
This routine sends the FTP USER and PASS commands in sequence to the remote host to log in the specified user with the specified password. The connection must have been opened previously. If there is already a user logged in and the specified username and password are identical to the current values, this routine has no effect.
The user must be logged in on the remote host using this routine or a combination of FTP_USER and FTP_PASSWORD (optionally, FTP_ACCOUNT) performed before calling any other routines for data transfer.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_NEEDACCT |
Server requires an account for login |
|
TCPWARE_LOGINFAIL |
Login attempt failed |
#include <descrip.h>
#include <ssdef.h>
#include "ftpdef.h"
main()
{
$DESCRIPTOR(host, "ds.internic.net");
$DESCRIPTOR(user, "anonymous");
$DESCRIPTOR(pswd, "your-name@your-site");
$DESCRIPTOR(dir, "rfc");
$DESCRIPTOR(file, "rfc-index.txt");
long ccb, status;
long debug = DEBUG_REPLY;
status = SS$_NORMAL;
ftp_allocate_ccb(&ccb);
status = ftp_open_connection(ccb, 0, &host, 0, 0);
if (!(status & 1))
{
printf("failed to make connection to %s", host.dsc$a_pointer);
goto error_nocon;
}
status = ftp_login_user (ccb, &user, &pswd);
if (!(status & 1))
{
printf("failed to login as %s", user.dsc$a_pointer);
goto error;
}
error:
ftp_close_connection (ccb);
return(status);
}
Opens an FTP connection to a remote host.
FTP_OPEN_CONNECTION(u_long ccb, [u_long *ia], [char *host-name], [u_int *port], [u_long *timeout]);
ccb
Identifies the CCB associated with the new connection.
ia
Internet address of the remote host to which you want to connect. The argument is the address of an unsigned longword containing the internet address in internet byte order (for example, internet address 1.2.3.4 is stored as 04030201 hex).
host-name
Host name of the remote host to which you want to connect. If the string is a valid internet address in a.b.c.d format, that address is used. Otherwise, the Socket Library's gethostbyname routine is used to determine the internet address from the host name.
port
Port number for the remote FTP server. If omitted, port number 21 is used.
timeout
Timeout time in seconds for establishing the FTP control connection. If omitted, the timeout time is 120 seconds (2 minutes).
This routine opens an active FTP connection to the specified remote host. Specify either the internet address or the host name. If you specify both, the internet address is used.
If you call this routine with a CCB with an active connection and the requested remote host is the same, SS$_WASSET is returned and connection is maintained. If you request a different remote host on an active CCB, the existing connection is closed and a new connection is opened.
|
SS$_NORMAL |
Normal successful completion |
|
SS$_WASSET |
Connection to specified node already established |
|
SS$_BADPARAM |
Missing internet address or host name |
|
SS$_UNREACHABLE |
Remote node is unreachable |
|
TCPWARE_REJECTED |
Remote server rejected the connection |
|
TCPWARE_OPENCTRL |
Failed to open control connection |
#include <descrip.h>
#include <ssdef.h>
#include "ftpdef.h"
main()
{
$DESCRIPTOR(host, "ds.internic.net");
$DESCRIPTOR(user, "anonymous");
$DESCRIPTOR(pswd, "your-name@your-site");
$DESCRIPTOR(dir, "rfc");
$DESCRIPTOR(file, "rfc-index.txt");
long ccb, status;
long debug = DEBUG_REPLY;
status = SS$_NORMAL;
ftp_allocate_ccb (&ccb);
status = ftp_open_connection(ccb, 0, &host, 0, 0);
if (!(status & 1))
{
printf("failed to make connection to %s", host.dsc$a_pointer);
goto error_nocon;
}
return (status);
}
Specifies the user password on the remote host.
FTP_PASSWORD(u_long ccb, char *password);
ccb
Identifies the CCB with the active connection.
password
Password of the user on the remote host.
This routine sends the FTP PASS command to specify the password of the user on the remote host. You must call this routine immediately after the FTP_USER routine if the latter returns a TCPWARE_NEEDPWD status.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_NEEDACCT |
Server requires an account for login |
|
TCPWARE_LOGINFAIL |
Login attempt failed |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Sets the protection buffer size as specified in RFC 2228 and RFC 4217. Only 0 (zero) is supported as per RFC 4217.
FTP_PBSZ(u_long ccb, char *size_string);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
size_string
Sets the size of the protection buffer. Currently only “0” (zero) is supported as per RFC 4217.
This routine sends an FTP PBSZ command to the FTP server.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_IVREQUEST |
Invalid request |
|
TCPWARE_NONODE |
Connection is not open |
Returns the current directory on the remote host.
FTP_PRINT_DIRECTORY(u_long ccb, char *directory, [int *length]);
ccb
Identifies the CCB with the active and logged-in connection.
directory
Returns the current directory on the remote host.
length
Returns the resulting length of the directory field.
This routine sends the FTP PWD command to retrieve the current working directory on the remote server. If the PWD command is rejected, the XPWD command is used.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_BADREPLY |
Unexpected reply from the server |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Sets the protection level specified in RFC 2228 and RFC 4217. Only C (clear) and P (private) are supported as per RFC 4217.
FTP_PROT(u_long ccb, char prot_level);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
prot_level
Specifies the protection level to use for data transfers. Only C (clear) and P (private) are supported as per RFC 4217.
This routine sends an FTP PROT command to the FTP server.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_IVREQUEST |
Invalid request |
|
TCPWARE_NONODE |
Connection is not open |
Copies a file to a remote host.
FTP_PUT_FILE(u_long ccb, char *source, [char *destination], [long *mode], [long *record-size]);
ccb
Identifies the CCB with the active and logged-in connection for the file transfer.
source
Source file on the local host.
destination
Destination file on the remote host. If omitted, the source filename and extensions are used.
mode
Transfer mode. See the Transferring Files section for a list of available transfer mode codes.
|
Note: Using mode causes the transfer mode set by FTP_SET_TYPE and FTP_SET_STRU to be ignored.
|
record-size
Record size of the local output file when transferring in IMAGE mode.
This routine sends the STOR command to copy the local file to the remote host.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_OPENIN |
Error opening a file for input |
|
TCPWARE_OPENDATA |
Failed to open data connection |
|
TCPWARE_SETPORT |
Failed to set up data connection |
|
TCPWARE_FILRDERR |
Error reading from or sending a file |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Sends an FTP command to the remote server.
FTP_QUOTE(u_long ccb, char *command);
ccb
Identifies the CCB with the active connection.
command
Command to be sent to the remote FTP server.
This routine sends the specified literal command string to the remote FTP server. For example, sending the HELP command with this routine obtains the help information from the remote server (as reply messages), if the remote server supports this command.
Note that you can use this routine only for simple commands, not for commands involving data transfer.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Renames a file on the remote host.
FTP_RENAME_FILE(u_long ccb, char *old-file, char *new-file);
ccb
Identifies the CCB with the active and logged-in connection.
old-file
File to rename on the remote host.
new-file
New filename on the remote host.
This routine sends the FTP RNFR and RNTO commands in sequence to rename a file on the remote server.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_RENAMEFAIL |
Failed to rename the remote file |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Sets the debugging mode for the FTP library.
FTP_SET_DEBUG(u_long ccb, u_long *flag, [void *output-routine]);
ccb
Identifies the CCB with the active and logged-in connection.
flag
Debugging flags to be set. Specify any of the following flag bits:
|
DEBUG_REPLY |
Output the replies received from the remote server |
|
DEBUG_COMMAND |
Output the FTP commands sent to the remote server |
The symbols for these flags are defined in the TCPWARE_INCLUDE:FTPDEF.H file.
output-routine
Address of a pointer to a routine that writes debugging text one line at a time. If omitted, LIB$PUT_OUTPUT is used. If you specify the routine of your own, it must have the same calling format as LIB$PUT_OUTPUT.
This routine sets the debugging mode for the FTP library. When the debugging flags are set, the FTP library outputs the debugging messages by LIB$PUT_OUTPUT, or a user-specified routine.
|
SS$_NORMAL |
Normal successful completion |
Sets the remote directory.
FTP_SET_DIRECTORY(u_long ccb, char *directory);
ccb
Identifies the CCB with the active and logged-in connection.
directory
Directory specification on the remote host. If omitted, the parent directory is used.
This routine sends the FTP CWD command to change the default directory on the remote server, and the CUP command to change the directory to the parent directory. If the directory specification is null, it changes the directory to the parent directory on the remote server. If the CWD and CUP commands are not accepted, the XCWD and XCUP commands are used.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_SETDEFAIL |
Failed to set default directory |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
status = ftp_set_directory(ccb,
&dir);
if (!(status & 1))
{
printf("failed to change directory to %s", dir.dsc$a_pointer);
goto error;
}
error:
ftp_close_connection(ccb);
Sets passive mode.
FTP_SET_PASV(u_long ccb, u_long *flag);
ccb
Identifies the CCB with the active and logged-in connection.
flag
Value 0 disables passive mode; value 1 enables passive mode.
This routine sets PASV (passive) mode. If enabled, the client sends the server the PASV command and the client initiates data connections to the server. If disabled, the client sends the server the PORT command and the server initiates the data connections.
|
SS$_NORMAL |
Normal successful completion |
Specifies the file structure.
|
Note: The mode arguments with FTP_GET_FILE and FTP_PUT_FILE cause the transfer mode set by FTP_SET_STRU to be ignored.
|
FTP_SET_STRU(u_long ccb, char *stru);
ccb
Identifies the CCB with the active connection for setting the file structure.
stru
Contains a character code that specifies the file structure. The valid types are:
|
F |
File (no record structure) |
|
R |
Record structure |
|
V |
VMS structure |
|
O |
O VMS structure (for backward compatibility) |
This routine sends the FTP STRU command to specify the file structure for the subsequent file transfer.
|
SS$_NORMAL |
Normal successful completion |
|
SS$_BADPARAM |
Bad parameter |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_UNSXFRFORM |
Unsupported transfer format |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Specifies the data representation type.
|
Note: The mode arguments with FTP_GET_FILE and FTP_PUT_FILE cause the transfer mode set by FTP_SET_TYPE to be ignored.
|
FTP_SET_TYPE(u_long ccb, char *type);
ccb
Identifies the CCB with the active connection.
type
Character string code that specifies the file representation type. The first character is the primary transfer mode, as follows:
|
A |
ASCII |
|
I |
Image |
EBCDIC type is not supported.
Do not use an additional character for transfer mode I. For transfer mode A, the second character must specify one of the following format control options:
|
N |
Non-print (no vertical format information) |
|
C |
FORTRAN carriage control |
TELNET format control is not supported.
This routine sends an FTP TYPE command to specify the file representation for the subsequent file transmission. The default representation type is AN (ASCII transfer in non-print mode).
|
SS$_NORMAL |
Normal successful completion |
|
SS$_BADPARAM |
Bad parameter |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_UNSTYPE |
Unsupported data representation type |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Specifies the user on the remote host.
FTP_USER(u_long ccb, char *username);
ccb
Identifies the CCB with an active connection for specifying the username.
username
Username on the remote host.
This routine sends an FTP USER command to the remote host to specify the user on the remote host. It may require a subsequent call to FTP_PASSWORD to complete the login. If there is already a user logged in on the specified connection, that user is logged out.
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NEEDPWD |
Server requires a password for login |
|
TCPWARE_LOGINFAIL |
Login attempt failed |