## TCPware V5.7 Programmer's Guide

- Introduction
- Building an FTP Client
- Connection Control Block
- Transferring Files
- Error Status Codes
- Library Routines

Chapter 7

FTP Library

# Introduction

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_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_PRINT_DIRECTORY | Returns the current directory on the remote host
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.

# Building an FTP Client

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

# Connection Control Block

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)

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_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)

# Transferring Files

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_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.

# Error Status Codes

To access TCPware error status codes, such as TCPWARE_REJECTED, define them in the code as follows:

globalvalue TCPWARE_REJECTED;

Then LINK with the definintions 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;
}

# Library Routines

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.

FTP_ACCOUNT

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)

FTP_ALLOCATE_CCB

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);
}

FTP_APPEND_FILE

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_CLOSE_CONNECTION

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);
}

FTP_CREATE_DIRECTORY

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)

FTP_DEALLOCATE_CCB

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);
}

FTP_DELETE_DIRECTORY

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)

FTP_DELETE_FILE

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)

FTP_GET_CCB

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

FTP_GET_FILE

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);
}

FTP_GET_LIST

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)

FTP_GET_NAME_LIST

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

See the FTP_GET_LIST routine.

FTP_LOGIN_USER

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);
}

FTP_OPEN_CONNECTION

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;
}

return (status);
}

FTP_PASSWORD

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_PRINT_DIRECTORY

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_PUT_FILE

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)

FTP_QUOTE

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)

FTP_RENAME_FILE

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)

FTP_SET_DEBUG

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

FTP_SET_DIRECTORY

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);

FTP_SET_PASV

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

FTP_SET_STRU

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)

FTP_SET_TYPE

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)

FTP_USER

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