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:
|
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 theFTP_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 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.
FTP_ACCOUNT (ccb, account)
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.
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 |
Allocates a connection control block (CCB).
FTP_ALLOCATE_CCB (ccb)
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
write only |
|
mechanism: |
by reference |
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 FTP-OpenVMS 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 (ccb, source, [destination], [mode], [record-size])
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.
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 |
Specifies the Authentication/Security mechanism to be used as per RFC 2228 and RFC 4217. Currently only TLS is supported.
FTP_AUTH(ccb, mechanism)
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.
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 |
|
TCPWARE_IVREQUEST |
Invalid request |
|
TCPWARE_REQFAIL |
Request failed. |
Specifies that the command channel return to clear text transmission.
FTP_CCC(ccb)
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.
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(CCB)
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.
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 (ccb)
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
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 (ccb, directory)
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.
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 |
Deallocates a CCB.
FTP_DEALLOCATE_CCB (ccb)
ccb
|
OpenVMS usage: |
address |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
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 (ccb, directory)
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.
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 |
Deletes a file on the remote host.
FTP_DELETE_FILE (ccb, file)
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
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 |
Gets information from a CCB field.
FTP_GET_CCB (ccb, field-code, value, length)
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.
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 (ccb, source, [destination], [mode], [record-size])
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.
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 |
$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 (ccb, [directory], output)
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.
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 |
Gets a filename listing on the remote host.
FTP_GET_NAME_LIST (ccb, [directory], output)
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.
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 (ccb, username, password)
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.
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 (ccb, [ia], [host-name], [port], [timeout])
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).
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 (ccb, password)
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.
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 |
Sets the protection buffer size as specified in RFC 2228 and RFC 4217. Only “0” (zero) is supported as per RFC 4217.
FTP_PBSZ(ccb, size_string)
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.
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 (ccb, directory, [length])
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.
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 |
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(ccb, prot_level)
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.
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 (ccb, source, [destination], [mode], [record-size])
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.
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 |
Sends an FTP command to the remote server.
FTP_QUOTE (ccb, command)
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.
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 |
Renames a file on the remote host.
FTP_RENAME_FILE (ccb, old-file, new-file)
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.
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 |
Sets the debugging mode for the FTP library.
FTP_SET_DEBUG (ccb, flag, [output-routine])
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.
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 (ccb, directory)
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.
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 |
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 (ccb, flag)
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.
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 (ccb, stru)
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) |
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 |
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 (ccb, type)
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.
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 |
Specifies the user on the remote host.
FTP_USER (ccb, username)
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.
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 |