Chapter 7
This chapter is for application programmers. It describes the FTP-OpenVMS library routines.
The FTP-OpenVMS library routines provide a programming interface to the FTP protocol. Use the FTP-OpenVMS 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 FTP-OpenVMS library routines follow the standard OpenVMS conventions for modular library routines. See the OpenVMS documentation on calling modular libraries for more information.
Because FTP-OpenVMS 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 FTP-OpenVMS library routines at the AST level.
The FTP-OpenVMS 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
Ctrl/Z
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
Ctrl/Z
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.
Table 7-1 lists CCB fields and their uses:
Table 7-1 CCB Fields (Continued)
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 before hand. |
|
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 FTP-OpenVMS 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 FTP-OpenVMS 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.
Format
FTP_ACCOUNT (ccb, account)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active connection.
account
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Name of the user account on the remote host.
Description
This routine sends the FTP ACCT command to specify the name of the account on the remote host.
Condition Values Returned
|
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).
Format
FTP_ALLOCATE_CCB (ccb)
Argument
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
write only |
|
mechanism: |
by reference |
Returns a pointer to the new CCB.
Description
This routine allocates a new CCB, initialize the resources and returns a pointer to it. A CCB must be allocated before all the subsequent calls to the FTP-OpenVMS library routines.
Condition Values Returned
Any condition value returned by LIB$GET_VM and LIB$GET_EF can be returned.
Example
#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.
Format
FTP_APPEND_FILE (ccb, source, [destination], [mode], [record-size])
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
source
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Source file on the local host.
destination
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Destination file on the remote host. If omitted, the source filename and extensions are used.
mode
|
OpenVMS usage: |
longword_signed |
|
type: |
longword (signed) |
|
access: |
read only |
|
mechanism: |
by reference |
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
|
OpenVMS usage: |
longword_signed |
|
type: |
longword (signed) |
|
access: |
read only |
|
mechanism: |
by reference |
Record size of the local output file when transferring in IMAGE mode.
Description
This routine sends the APPE command to append the local file to the file on the remote host.
Condition Values Returned
|
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) |
FTP_AUTH
Specifies the Authentication/Security mechanism to be used as per RFC 2228 and RFC 4217. Currently only TLS is supported.
Format
FTP_AUTH(ccb, mechanism)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
mechanism
|
OpenVMS usage: |
address |
|
type: |
string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Specifies the Authentication/Security mechanism to use. Currently only "TLS" is supported.
Description
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.
Condition Values Returned
|
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. |
FTP_CCC
Specifies that the command channel return to clear text transmission.
Format
FTP_CCC(ccb)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
Description
This routine sends an FTP CCC command to the FTP server.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
FTP_CHECK_FEATURES
Sends the FEAT command to the server and builds the bit mask of supported features.
Format
FTP_CHECK_FEATURES(CCB)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
Description
This routine sends an FTP FEAT command to the FTP server and interprets the response to build a bit mask of supported optional features.
Condition Values Returned
None.
Closes the connection to the remote FTP server if one is open.
Format
FTP_CLOSE_CONNECTION (ccb)
Argument
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB whose active FTP connection is to be closed.
Description
This routine sends an FTP QUIT command to the remote FTP server to close the connection and free up the resources allocated to it.
Condition Value Returned
|
SS$_NORMAL |
Normal successful completion |
Example
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.
Format
FTP_CREATE_DIRECTORY (ccb, directory)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
directory
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Directory specification on the remote host.
Description
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.
Condition Values Returned
|
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.
Format
FTP_DEALLOCATE_CCB (ccb)
Argument
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
Identifies the CCB you want to deallocate.
Description
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.
Condition Value Returned
|
SS$_NORMAL |
Normal successful completion |
Example
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.
Format
FTP_DELETE_DIRECTORY (ccb, directory)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
directory
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Directory to be deleted on the remote host.
Description
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.
Condition Values Returned
|
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.
Format
FTP_DELETE_FILE (ccb, file)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
file
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
File specification of the file to be deleted on the remote host
Description
This routine sends an FTP DELE command to delete a specified file on the remote server.
Condition Values Returned
|
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.
Format
FTP_GET_CCB (ccb, field-code, value, length)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB from which information is retrieved.
field-code
|
OpenVMS usage: |
longword_signed |
|
type: |
longword (signed) |
|
access: |
read only |
|
mechanism: |
by reference |
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
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
write only |
|
mechanism: |
by reference |
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
|
OpenVMS usage: |
word_signed |
|
type: |
word (signed) |
|
access: |
write only |
|
mechanism: |
by reference |
Returns the resulting length of the value field if the data type of the returned value is STRING.
Description
This routine returns the contents of the specified field from the CCB.
Condition Values Returned
|
SS$_NORMAL |
Normal, successful completion |
|
SS$_BADPARAM |
Bad parameter specified |
Copies a file from a remote host.
Format
FTP_GET_FILE (ccb, source, [destination], [mode], [record-size])
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
source
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Source file on the remote host.
destination
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Destination file on the local host. If omitted, the source filename and extensions are used.
mode
|
OpenVMS usage: |
longword_signed |
|
type: |
longword (signed) |
|
access: |
read only |
|
mechanism: |
by reference |
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
|
OpenVMS usage: |
longword_signed |
|
type: |
longword (signed) |
|
access: |
read only |
|
mechanism: |
by reference |
Record size of the local output file when transferring in IMAGE mode.
Description
This routine sends an FTP RETR command to transfer a remote file to the local host.
Condition Values Returned
|
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) |
Example
$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.
Format
FTP_GET_LIST (ccb, [directory], output)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
directory
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Directory specification on the remote host. If omitted, the current remote directory is used.
output
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Specifies the local file where the output of the remote directory listing is stored.
Description
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.
Condition Values Returned
|
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.
Format
FTP_GET_NAME_LIST (ccb, [directory], output)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
directory
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Directory specification on the remote host. If omitted, the current remote directory is used.
output
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Specifies the local file where the output of the remote directory listing is stored.
Description
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.
Condition Values Returned
Authorizes the user on the remote host.
Format
FTP_LOGIN_USER (ccb, username, password)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB of the active network connection.
username
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Username on the remote host.
password
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Password of the user on the remote host.
Description
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.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NONODE |
Connection is not open |
|
TCPWARE_NEEDACCT |
Server requires an account for login |
|
TCPWARE_LOGINFAIL |
Login attempt failed |
Example
#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.
Format
FTP_OPEN_CONNECTION (ccb, [ia], [host-name], [port], [timeout])
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB associated with the new connection.
ia
|
OpenVMS usage: |
unsigned_long |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
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
|
OpenVMS usage: |
character_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
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
|
OpenVMS usage: |
unsigned_word |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
Port number for the remote FTP server. If omitted, port number 21 is used.
timeout
|
OpenVMS usage: |
unsigned_longword |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
Timeout time in seconds for establishing the FTP control connection. If omitted, the timeout time is 120 seconds (2 minutes).
Description
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.
Condition Values Returned
|
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 |
Example
#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;
}
Specifies the user password on the remote host.
Format
FTP_PASSWORD (ccb, password)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active connection.
password
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Password of the user on the remote host.
Description
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.
Condition Values Returned
|
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) |
FTP_PBSZ
Sets the protection buffer size as specified in RFC 2228 and RFC 4217. Only "0" (zero) is supported as per RFC 4217.
Format
FTP_PBSZ(ccb, size_string)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
size_string
|
OpenVMS usage: |
address |
|
type: |
string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Sets the size of the protection buffer. Currently only "0" (zero) is supported as per RFC 4217.
Description
This routine sends an FTP PBSZ command to the FTP server.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_IVREQUEST |
Invalid request |
|
TCPWARE_NONODE |
Connection is not open |
Returns the current directory on the remote host.
Format
FTP_PRINT_DIRECTORY (ccb, directory, [length])
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
directory
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
write only |
|
mechanism: |
by descriptor |
Returns the current directory on the remote host.
length
|
OpenVMS usage: |
word_signed |
|
type: |
word (signed) |
|
access: |
write only |
|
mechanism: |
by reference |
Returns the resulting length of the directory field.
Description
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.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_BADREPLY |
Unexpected reply from the server |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
FTP_PROT
Sets the protection level specified in RFC 2228 and RFC 4217. Only "C" (clear) and "P" (private) are supported as per RFC 4217
Format
FTP_PROT(ccb, prot_level)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
prot_level
|
OpenVMS usage: |
address |
|
type: |
character |
|
access: |
read only |
|
mechanism: |
by value |
Specifies the protection level to use for data transfers. Only "C" (clear) and "P" (private) are supported as per RFC 4217.
Description
This routine sends an FTP PROT command to the FTP server.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_IVREQUEST |
Invalid request |
|
TCPWARE_NONODE |
Connection is not open |
Copies a file to a remote host.
Format
FTP_PUT_FILE (ccb, source, [destination], [mode], [record-size])
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection for the file transfer.
source
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Source file on the local host.
destination
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Destination file on the remote host. If omitted, the source filename and extensions are used.
mode
|
OpenVMS usage: |
longword_signed |
|
type: |
longword (signed) |
|
access: |
read only |
|
mechanism: |
by reference |
Transfer mode. See 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
|
OpenVMS usage: |
longword_signed |
|
type: |
longword (signed) |
|
access: |
read only |
|
mechanism: |
by reference |
Record size of the local output file when transferring in IMAGE mode.
Description
This routine sends the STOR command to copy the local file to the remote host.
Condition Values Returned
|
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.
Format
FTP_QUOTE (ccb, command)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active connection.
command
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Command to be sent to the remote FTP server.
Description
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.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection(the connection is closed) |
Renames a file on the remote host.
Format
FTP_RENAME_FILE (ccb, old-file, new-file)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
old-file
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
File to rename on the remote host.
new-file
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
New filename on the remote host.
Description
This routine sends the FTP RNFR and RNTO commands in sequence to rename a file on the remote server.
Condition Values Returned
|
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.
Format
FTP_SET_DEBUG (ccb, flag, [output-routine])
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
flag
|
OpenVMS usage: |
longword_unsigned |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
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
|
OpenVMS usage: |
address of pointer to procedure |
|
type: |
address of address of procedure value |
|
access: |
read only |
|
mechanism: |
passing by reference a pointer to the address of a 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.
Description
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.
Condition Value Returned
|
SS$_NORMAL |
Normal successful completion |
Sets the remote directory.
Format
FTP_SET_DIRECTORY (ccb, directory)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
directory
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Directory specification on the remote host. If omitted, the parent directory is used.
Description
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.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_SETDEFAIL |
Failed to set default directory |
|
TCPWARE_CTRLERR |
Unexpected error processing the control connection (the connection is closed) |
Example
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.
Format
FTP_SET_PASV (ccb, flag)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active and logged-in connection.
flag
|
OpenVMS usage: |
longword_unsigned |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
Value 0 disables passive mode; value 1 enables passive mode.
Description
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.
Condition Values Returned
|
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.
Format
FTP_SET_STRU (ccb, stru)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active connection for setting the file structure.
stru
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
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) |
Description
This routine sends the FTP STRU command to specify the file structure for the subsequent file transfer.
Condition Values Returned
|
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.
Format
FTP_SET_TYPE (ccb, type)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with the active connection.
type
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
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.
Description
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).
Condition Values Returned
|
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.
Format
FTP_USER (ccb, username)
Arguments
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Identifies the CCB with an active connection for specifying the username.
username
|
OpenVMS usage: |
char_string |
|
type: |
character string |
|
access: |
read only |
|
mechanism: |
by descriptor |
Username on the remote host.
Description
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.
Condition Values Returned
|
SS$_NORMAL |
Normal successful completion |
|
TCPWARE_NEEDPWD |
Server requires a password for login |
|
TCPWARE_LOGINFAIL |
Login attempt failed |
