Copyright: Microsoft SNA Server Copyright 1994
Citation: Microsoft SNA Server Copyright 1994


Microsoft SNA Server Master Table of Contents
Microsoft SNA Server

Master Table of Contents

	SNA Server Enhancements Guide
	SNA Server Installation Guide
	SNA Server Administration Guide
	Managing Microsoft SNA Server
	SNA Server Planning Guide
	SNA Server TN3270 Service
	3270/5250 Applet User's Guide
	SNA Server Reference
	SNA Server Glossary
	APPC Programmer's Guide
	AFTP API Programmer's Guide
	CPI-C Programmer's Guide
	LUA Programmer's Guide
	SNA Device Interface Specification
	3270 Emulator Interface Specification
	Comprehensive Index


How to Use This Guide
AFTP API Programmer's Guide

How to Use This Guide

This manual covers the following topics:

Before You Begin

Introduction to the AFTP API Programmer's Guide.

Chapter 1 "API for APPC File Transfer Protocol"

Describes constants, types and conventions for use in the AFTP API that are not standard to C programming.

Chapter2, "AFTP API Call Reference

Provides an alphabetical reference for all of the API calls for the APPC File Transfer Protocol (AFTP).

Chapter 3, "AFTP Return Codes"

Lists the possible return codes that can be issued for each AFTP API call.

Appendix A, "Entry Point Mappings"

Lists all AFTP API call mappings.

Appendix B, "Sample Program for AFTP API"

An example program to show use of the AFTP programming interface.

Glossary

Definitions for terms and phrases used in this document.


Before You Begin

The APPC Application Suite provides application program interfaces (APIs) to its APPC File Transfer Protocol (AFTP) functions. This book provides the information you will need to write an application program to implement AFTP client functions.


Who Should Use This Book
Before You Begin

Who Should Use This Book

This book is written for application programmers. It assumes that you are familiar with writing C language applications. Although the APPC Application Suite API is based on common programming interface for communications (CPI-C) and advanced program-to-program communications (APPC), you do not necessarily need to know these concepts to successfully write applications based on this API.


API For APPC File Transfer Protocol
Chapter 1

API For APPC File Transfer Protocol

The APPC File Transfer Protocol (AFTP) application programming interface (API) is a set of C routines that provides APPC file transfer capabilities. This API makes file transfer programming easier by allowing you to access routines that will interact with any AFTP server. The AFTP API adheres to the AFTP line flow standards. All AFTP client applications will send the same set of line flows over the network to the AFTP server.


AFTP Defined Constants, Standard Types and Conventions
API For APPC File Transfer Protocol

AFTP Defined Constants, Standard Types and Conventions

This section describes constants, types and conventions for use in the AFTP API that are not standard to C programming.


Defined Constants
API For APPC File Transfer Protocol

Defined Constants

AFTP constant definitions have been created for the sizes of the buffers that are passed across the API. All buffers of the specified type must be at least the size of the defined constant to guarantee the requested call will not fail with a buffer size error.

The constants are defined in the header file for the AFTP API.

Table 1. AFTP Size Constants

CONSTANT	MINIMUM BUFFER SIZE FOR	VALUE
AFTP_DATA_TYPE_SIZE	data_type_size	64
AFTP_DATE_MODE_SIZE	date_mode_size	64
AFTP_FILE_NAME_SIZE	dir_entry_size ordir_entry_size or path_buffer_length	512
AFTP_FQLU_NAME_SIZE	destination_size or partner_LU_name_size	64
AFTP_MESSAGE_SIZE	error_str_size	2048
AFTP_MODE_NAME_SIZE	mode_name_size	8
AFTP_PASSWORD_SIZE	password_size	10
AFTP_RECORD_FORMAT_SIZE	record_format_size	64
AFTP_SYSTEM_INFO_SIZE	system_info_size	512
AFTP_TP_NAME_SIZE	tp_name_size	64
AFTP_USERID_SIZE	userid_size	10
AFTP_WRITE_MODE_SIZE	write_mode_size	64


Standard Types
API For APPC File Transfer Protocol

Standard Types

Type definitions are available for many parameters to the AFTP API calls. For example, the AFTP type AFTP_LENGTH_TYPE is an alias for the C type unsigned long.

Use the AFTP types instead of the corresponding C types. Doing so will protect you from changes to the parameters in future releases. If you have used the AFTP types, you will only need to recompile your code to use the new API definitions. If you have used the C types, you will need to modify your program source to reflect changes to the new C types.

The AFTP API avoids complex structures and pointers to structures for type definitions. These complex structures might not be supported in all languages. The only exception is the string construct which is found in many languages.

Table 2. AFTP Standard Types

TYPE	DESCRIPTION
AFTP_HANDLE_TYPE	The AFTP connection object id
AFTP_ALLOCATION_SIZE_TYPE	The file allocation size
AFTP_BLOCK_SIZE_TYPE	The file block size
AFTP_BOOLEAN_TYPE	A boolean (FALSE=0, TRUE=1) type
AFTP_DATA_TYPE_TYPE	The file data types that can be transferred
AFTP_DATE_MODE_TYPE	The date mode used for transferred files
AFTP_DETAIL_LEVEL_TYPE	Amount of information to be output when AFTP generates error messages
AFTP_FILE_TYPE_TYPE	The kind of a file (directory/file) listed by AFTP
AFTP_INFO_LEVEL_TYPE	The amount of information listed for a file by AFTP
AFTP_LENGTH_TYPE	The size of input buffers, and the actual returned length of buffers in AFTP
AFTP_RETURN_CODE_TYPE	The return codes output by AFTP
AFTP_RECORD_FORMAT_TYPE	The file record formats
AFTP_RECORD_LENGTH_TYPE	The file record length
AFTP_SECURITY_TYPE	The APPC security types
AFTP_TRACE_LEVEL_TYPE	The levels of tracing information output by AFTP
AFTP_VERSION_TYPE	The AFTP program version numbers
AFTP_WRITE_MODE_TYPE	The different ways that AFTP can write to a file


Conventions
API For APPC File Transfer Protocol

Conventions

Null-Terminated Strings

The AFTP API does not require input strings to be null-terminated. The AFTP API also does not guarantee that the output strings are null terminated. The return size does not include the null terminator in v the size, if there is one.

The C programmer should be aware of the fact that strings are handled differently within AFTP than they are in the C standard library. All API calls receiving strings as input require both the string itself, and the length of the string. The strlen() function can be used for this. The null terminator must not be counted as part of the string length. API calls which output strings require three string related parameters:

•	The string.

•	The length of the string buffer that has been allocated by the calling program. Both of these are input to the API, with the string being modified.

•	The actual length of the string that is output. AFTP output strings are not null terminated. In order for the C programmer to use them as standard C strings, a null character must be added to the end of the string.

AFTP_ENTRY

The AFTP API calls do not return a value. Rather, the return code parameter is set to indicate the success or failure of the call. The programmer should check the return code parameter after each call and handle error values appropriately.

The C keyword void is not used for entry points in the AFTP API. Instead, AFTP_ENTRY has been defined. AFTP_ENTRY is defined differently depending on the operating system the AFTP client will be created on.

AFTP_PTR

The C pointer indicator '*' is not used in the AFTP API. Instead, AFTP_PTR has been defined. AFTP_PTR is defined differently depending on the operating system the AFTP client will be created on.


Compiling the Aftp Application
API For APPC File Transfer Protocol

Compiling the AFTP Application

MVS

To develop an application that uses the AFTP API on MVS, follow these steps:

Note  This process assumes all AFTP program files have been successfully installed with the provided JCL for installing AFTP.

1.	Include this header file in your source modules: APPFFTP.

2.	Define CM_MVS when you compile your source.

3.	Edit the APPFAPIJ JCL file and make the changes indicated in the prolog comments at the top of the file.

4.	Submit the APPFAPIJ JCL.

VM

To access the AFTP API calls from your application you must

1.	Include this header file in your source modules: APPFFTP H.

2.	Define CM_VM when you compile your source.

3.	Add APPFAPIL TXTLIB to your GLOBAL TXTLIB statement. All textdecks are packaged into this textlib.


Overview of API Calls
API For APPC File Transfer Protocol

Overview of API Calls

The calls of the AFTP API can be organized into the following categories:

•	Create or destroy an AFTP connection object

•	Establish a connection to the AFTP server

•	Query connection characteristics

•	Transfer files

•	Specify file transfer characteristics

•	Query file transfer characteristics

•	List files on the AFTP server

•	List files on the AFTP client

•	Perform directory manipulation

•	Perform file manipulation

•	Query system information

•	Generate message strings

•	Control trace information

•	Miscellaneous


Create or Destroy an AFTP Connection Object
API For APPC File Transfer Protocol

Creating or Destroying an AFTP Connection Object

The connection object represents an object-oriented approach to AFTP. An AFTP connection object represents a connection (not necessarily active) to a partner computer. Many of the other AFTP API calls require an AFTP connection object as input. When the program has finished using AFTP API calls, it should destroy the connection object.

AFTP_CREATE()

Creates an AFTP connection object and assigns a unique identifier to it. The connection object is accessed by its connection id. The connection object is never automatically destroyed. This allows you to connect to an AFTP server once, or reconnect numerous times using the same AFTP connection object.

AFTP_DESTROY()

Destroys the AFTP connection object and recovers all resources associated with it. Once the AFTP connection object has been destroyed, that object must not be used again. If you need a connection object again, create another one.


Establish a Connection to the AFTP Server Computer
API For APPC File Transfer Protocol

Establishing a Connection to the AFTP Server Computer

In order for the AFTP client to communicate with an AFTP server, certain communications parameters must be set. Most of the communications parameters have default values. The destination does not have a default value and must be set explicitly. Once the parameters are set as desired, the connection to the server can take place.

These are the API calls you use to manage your connection to the AFTP server:

AFTP_CLOSE()

Closes a connection to the AFTP server once processing is complete.

AFTP_CONNECT()

Establishes the connection to the AFTP server for file transfer.

AFTP_SET_DESTINATION()

Identifies the server computer name to which the AFTP connection will be established. This server computer will run the AFTP server program.

AFTP_SET_MODE_NAME()

Sets the mode name to be used for this connection. The default mode name is #BATCH.

AFTP_SET_PASSWORD()

Sets the password used for APPC security type PROGRAM. Using this call automatically sets the security type to PROGRAM.

AFTP_SET_SECURITY_TYPE()

Sets the APPC security used for the AFTP connection to the AFTP server.

AFTP_SET_TP_NAME()

Sets the transaction program name to be used for this connection. The default transaction program name is AFTPD.

AFTP_SET_USERID()

Sets the user ID used for APPC security type PROGRAM. Using this call automatically sets the security type to PROGRAM.


Querying Connection Characteristics
API For APPC File Transfer Protocol

Querying Connection Characteristics

Use these API calls to query the characteristics of the connection to the AFTP server.

AFTP_EXTRACT_DESTINATION()

Extracts the identity of the server computer on which the AFTP server runs.

AFTP_EXTRACT_MODE_NAME()

Extracts the mode name used for this connection.

AFTP_EXTRACT_PARTNER_LU_NAME()

Extracts the fully qualified LU name of the AFTP server computer.

AFTP_EXTRACT_PASSWORD()

Extracts the password used for this connection.

AFTP_EXTRACT_SECURITY_TYPE()

Extracts the security type used for this connection.

AFTP_EXTRACT_TP_NAME()

Extracts the transaction program name used for this connection.

AFTP_EXTRACT_USERID()

Extracts the user ID used for this connection.


Transferring Files
API For APPC File Transfer Protocol

Transferring Files

The primary purpose of the file transfer protocol is to exchange files between the AFTP client and AFTP server programs. Through the API, the AFTP client program can send a file to the AFTP server, and receive a file from the AFTP server.

Use these API calls to transfer files between the client and server.

AFTP_QUERY_BYTES_TRANSFERRED()

Outputs the number of bytes transferred by either the aftp_send_file() or aftp_receive_file() calls.

AFTP_RECEIVE_FILE()

Receives a single file from the AFTP server.

AFTP_SEND_FILE()

Sends a single file to the AFTP server.


Specifying File Transfer Characteristics
API For APPC File Transfer Protocol

Specifying File Transfer Characteristics

AFTP supports a variety of file transfer attributes. Both text and binary files can be transferred. The data structure of the files can be set by the programmer for mainframe applications. This allows several variations of record-based files to be transferred.

Use these API calls to specify file transfer characteristics.

AFTP_SET_ALLOCATION_SIZE()

Sets the amount of space allocated for the file which is being written.

AFTP_SET_BLOCK_SIZE()

Sets the size of a data block for the file which is being written.

AFTP_SET_DATA_TYPE()

Sets the way in which the data transmitted is interpreted.

AFTP_SET_DATE_MODE()

Sets how the date will be represented when the file is written (either received or sent). The new file can use the current date/time stamp or the date/time stamp of the original file.

AFTP_SET_RECORD_FORMAT()

Sets the record format of the file transmitted.

AFTP_SET_RECORD_LENGTH()

Sets the length of the file record transmitted.

AFTP_SET_WRITE_MODE()

Sets the type of write operation which will occur when the transmitted file is written (either received or sent).


Querying File Transfer Characteristics
API For APPC File Transfer Protocol

Querying File Transfer Characteristics

Use these API calls to query the file transfer attributes.

AFTP_EXTRACT_ALLOCATION_SIZE()

Extracts the amount of space allocated for the file which is being transmitted.

AFTP_EXTRACT_BLOCK_SIZE()

Extracts the size of a data block for the file which is being transmitted.

AFTP_EXTRACT_DATA_TYPE()

Extracts the way in which the transmitted data is interpreted.

AFTP_EXTRACT_DATE_MODE()

Extracts how the date will be represented when the file is written.

AFTP_EXTRACT_RECORD_FORMAT()

Extracts the record format of the file transmitted.

AFTP_EXTRACT_RECORD_LENGTH()

Extracts the length of the file record transmitted.

AFTP_EXTRACT_WRITE_MODE()

Extracts the type of write operation which will occur when the transmitted file is written.


Listing Files on the AFTP Server Computer
API For APPC File Transfer Protocol

Listing Files on the AFTP Server Computer

File list facilities can be used to support wildcard transfers from the AFTP server. The wildcard processing is kept off the send and receive calls to make the calls as portable as possible. Obtaining a complete directory listing requires three calls: open, read, and close.

AFTP_DIR_CLOSE()

Closes an active directory listing on the AFTP server.

AFTP_DIR_OPEN()

Begins a directory listing operation on the AFTP server. The directory open call sets up the search specifications:

•	File specification which is to be matched

•	Whether directories, files, or both should be included in the search

•	The type of information desired (file names only or file names with attributes)

AFTP_DIR_READ()

Gets the next file from the directory listing on the AFTP server. A text string describing the file will be returned. The format of the information returned depends on the parameters specified on the aftp_dir_open() call.


Listing Files on the AFTP Client Computer
API For APPC File Transfer Protocol

Listing Files on the AFTP Client Computer

File list facilities can be used to support wildcard transfers to the AFTP server. The wildcard processing is kept off the send and receive primitives to make the primitives as portable as possible. Obtaining a complete directory listing requires three calls: open, read, and close.

AFTP_LOCAL_DIR_CLOSE()

Closes an active directory listing on the AFTP client.

AFTP_LOCAL_DIR_OPEN()

Begins a directory listing operation on the AFTP client. The directory open call sets up the search specifications:

•	File specification to be matched

•	Whether directories, files, or both should be included in the search

•	The type of information desired (file names only or file names with attributes)

AFTP_LOCAL_DIR_READ()

Gets the next file from the directory listing on the AFTP client. A text string describing the file will be returned. The format of the information returned depends upon the parameters specified on the aftp_local_dir_open() call.


Performing Directory Manipulation
API For APPC File Transfer Protocol

Performing Directory Manipulation

AFTP provides methods of traversing and modifying the directory structure on the AFTP server computer. It is possible to build recursive copy routines for entire directory trees using these calls. AFTP also maintains the current directory on the AFTP server. This provides the user with a method of specifying a file name without specifying the entire directory path to that file on the AFTP server.

Use these API calls to manage directories on the client and server.

AFTP_CHANGE_DIR()

Changes the current working directory on the AFTP server.

AFTP_CREATE_DIR()

Makes a new directory on the AFTP server.

AFTP_QUERY_CURRENT_DIR()

Outputs the current working directory on the AFTP server.

AFTP_REMOVE_DIR()

Removes an existing directory on the AFTP server.

AFTP provides methods to query and traverse the directory structure on the AFTP client computer. AFTP maintains the current directory on the AFTP client. This provides the user with a method of specifying a file name without specifying the entire directory path to that file on the AFTP client.

AFTP_LOCAL_CHANGE_DIR()

Changes the current working directory on the AFTP client.

AFTP_LOCAL_QUERY_CURRENT_DIR()

Outputs the current working directory on the AFTP client.


Performing File Manipulation
API For APPC File Transfer Protocol

Performing File Manipulation

The following two calls provide additional file functions which allow modifications to files on the AFTP server without using the aftp_send_file() call. It is possible to rename a file on the AFTP server computer as long as the rename does not cross device boundaries. It is also possible to delete files on the AFTP server computer.

AFTP_DELETE()

Deletes a file on the AFTP server.

AFTP_RENAME()

Renames a file on the AFTP server.


Querying System Information
API For APPC File Transfer Protocol

Querying System Information

The query system calls can be used to learn more information about the AFTP client and AFTP server computers.

AFTP_QUERY_LOCAL_SYSTEM_INFO()

Outputs a string describing the AFTP client operating system.

AFTP_QUERY_LOCAL_VERSION()

Outputs the major and minor AFTP client version numbers.

AFTP_QUERY_SYSTEM_INFO()

Outputs a string describing the AFTP server operating system.


Generating Message Strings
API For APPC File Transfer Protocol

Generating Message Strings

AFTP allows the caller to use consistent strings for AFTP transfer characteristics. AFTP will output the string to use when queried. It is also possible to output standard text messages for AFTP errors. The other API calls return an AFTP return code which can be queried to determine if an error message should be output.

Use these API calls to get text strings to use in messages issued by your application.

AFTP_FORMAT_ERROR()

Generates text output for the current AFTP error. This should be used to output error information to the user when an AFTP call returns a bad return code.

AFTP_GET_DATA_TYPE_STRING()

Outputs the string corresponding to an input data type value.

AFTP_GET_DATE_MODE_STRING()

Outputs the string corresponding to an input date mode value.

AFTP_GET_RECORD_FORMAT_STRING()

Outputs the string corresponding to an input record format value.

AFTP_GET_WRITE_MODE_STRING()

Outputs the string corresponding to an input write mode value.


Controlling Trace Information
API For APPC File Transfer Protocol

Controlling Trace Information

Use these API calls to control tracing of AFTP activity.

AFTP_EXTRACT_TRACE_LEVEL()

Extracts the current trace level.

AFTP_SET_TRACE_FILENAME()

Sets the name of the file to be used for trace output.

AFTP_SET_TRACE_LEVEL()

Sets the amount of trace data to be captured.


Miscellaneous Information
API For APPC File Transfer Protocol

Miscellaneous

AFTP provides a method of loading the AFTP initialization file which

contains user permission and file mapping information.

AFTP_LOAD_INI_FILE()

Loads the AFTP initialization file into memory.


CHAPTER 2. AFTP API Call Reference
CHAPTER 2

AFTP API Call Reference

This chapter provides an alphabetical reference for all of the API calls for the APPC File Transfer Protocol (AFTP). Program examples are provided for each call to illustrate its use in a program.


AFTP_CHANGE_DIR
AFTP API Call Reference

AFTP_CHANGE_DIR

Use this call to change the current working directory on the AFTP server. A connection to the AFTP server must be established before using this call.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_change_dir(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR directory,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIRECTORY

(input) The new current working directory name. The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The directory specified can be either an absolute or a relative path name.

LENGTH

(input) The length of the directory parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{
    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /* The value used will vary based on platform:

     *   VM common naming:       directory = "/d"

     *   VM native naming:       directory = "/d"

     *   MVS PDS common naming:  directory = "/user.clist/"

     *   MVS PDS native naming:  directory = "'user.clist'"

     *   MVS data set prefix common:  directory = "/user.qual.a."

     *   MVS data set prefix native:  directory =
         "'user.qual.a.'"

     *   NT* common naming:    directory = "/c:/nt"

     *   NT native naming:     directory = "c:\\nt"

     */

    static unsigned char AFTP_PTR directory = "/user.clist/"; /*
    MVS */

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

     /*

      * Specify the new current working directory name

      * using the COMMON name format.

      */

     aftp_change_dir(

         connection_id,

         directory,

         (AFTP_LENGTH_TYPE)strlen(directory),

         &aftp_rc);

     if (aftp_rc != AFTP_RC_OK) {

         fprintf(stderr, "Error changing AFTP directory.\n");

     }

}

Line Flows

The directory name is sent to the AFTP server, and the call waits for a response indicating the success or failure of the change directory operation.


AFTP_CLOSE
AFTP API Call Reference

AFTP_CLOSE

Use this call to close an active connection. A connection to the AFTP server must be established before using this call.

AFTP_ENTRY aftp_close(
AFTP_HANDLE_TYPE connection_id,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP object connection originally created with aftp_create().

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

     aftp_close(connection_id, &aftp_rc);

     if (aftp_rc != AFTP_RC_OK) {

         fprintf(

             stderr,

             "Error on aftp_close(): %s\n",

             aftp_rc);

}

Line Flows

The close operation forces a Deallocate(FLUSH) to flow to the server.


AFTP_CONNECT
AFTP API Call Reference

AFTP_CONNECT

Use this call to establish a connection to the AFTP server. You must identify the destination of the AFTP server with the aftp_set_destination() call prior to issuing this call.

AFTP_ENTRY aftp_connect(
AFTP_HANDLE_TYPE connection_id,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /*

     * Before issuing the example call, you must have:

     * a connection_id, use:  aftp_create()

     * a destination, use:    aftp_set_destination()

     */

    /*

     * Establish a connection to the server

     */

    aftp_connect(connection_id, &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(

            stderr,

            "Error on aftp_connect(): %s\n",

            aftp_rc);

    }

}

Line Flows

•	The aftp_connect() call will cause an Allocate to flow to the server.

•	Once a conversation is established, an exchange of version numbers and capabilities occurs between the client and the server. Therefore, this call does not return until AFTP verifies that the server program is running correctly on the remote system or an error occurs.


AFTP_CREATE
AFTP API Call Reference

AFTP_CREATE

Use this call to create an AFTP connection object which can be used to connect to an AFTP server.

AFTP_ENTRY aftp_create(
AFTP_HANDLE_TYPE connection_id,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(output) Handle of the AFTP connection object that was created by this call. All subsequent AFTP calls must use a previously created AFTP connection object.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE aftp_rc;

    AFTP_HANDLE_TYPE      connection_id;

    /*

     * There are no prerequisite calls for this call.

     */

    /*

     * Create the connection object that we will use for AFTP.

     */

    aftp_create(connection_id, &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error creating an AFTP object.\n");

    }

}

Line Flows

None.


AFTP_CREATE_DIR
AFTP API Call Reference

AFTP_CREATE_DIR

Use this call to create a new directory on the AFTP server. A connection to the AFTP server must be established before using this call.

PLATFORM DIFFERENCES:

1.	On VM, this call is not supported. If issued, the call fails with return code AFTP_RC_FAIL_NO_RETRY.

2.	On MVS, partitioned data sets act as the directory structure. This call creates a partitioned data set with the name specified.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_create_dir(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR directory,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIRECTORY

input) The name of the directory name to be created. The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The directory specified can be either an absolute or relative path name.

LENGTH

(input) The length of the directory parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /* The value used for filespec will vary based on platform:

     *   VM  not supported

     *   MVS PDS common naming:  directory="/user.clist/"

     *   MVS PDS native naming:  directory="'user.clist'"

     *   NT native naming:     directory="d:\\newdir"

     *   NT common naming:     directory="/d:/newdir"

     */

    static unsigned char AFTP_PTR directory = "/user.clist/";

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    aftp_create_dir(

        connection_id,

        directory,

        (AFTP_LENGTH_TYPE)strlen(directory),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error creating directory.\n");

    }

}

Line Flows

The directory name is sent to the AFTP server and the call waits for a response indicating the success or failure of the create directory operation.


AFTP_DELETE
AFTP API Call Reference

AFTP_DELETE

Use this call to delete a single file on the AFTP server. A connection to the AFTP server must be established before using this call.

AFTP_ENTRY aftp_delete(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR filename,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

FILENAME

(input) The name of the file to be removed. The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can contain either an absolute or relative path name.

LENGTH

(input) The length of the filename parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE       connection_id;

    AFTP_RETURN_CODE_TYPE  aftp_rc;

    /* The value used for filespec will vary based on platform:

     *   VM common naming:       filespec="/a/foo*"

     *   VM native naming:       filespec="foo*.*.a"

     *   MVS PDS common naming:  filespec="/user.clist/foo*"

     *   MVS PDS native naming:  filespec="'user.clist(foo*)'"

     *   MVS sequential common:  filespec="/user.qual*.a*.**"

     *   MVS sequential native:  filespec="'user.qual*.a*.**'"

     */

    static unsigned char AFTP_PTR filespec = "/user.clist/foo*";

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    /*

     * Delete a file

     */

    aftp_delete(

        connection_id,

        filespec,

        (AFTP_LENGTH_TYPE)strlen(filespec),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error deleting AFTP file.\n");

    }

}

Line Flows

The file name is sent to the AFTP server and the call waits for a response indicating the success or failure of the delete file operation.


AFTP_DESTROY
AFTP API Call Reference

AFTP_DESTROY

Use this call to destroy an AFTP connection object. Once an AFTP connection object is destroyed, it cannot be used again.

You should issue the aftp_close() call to end the connection before you issue this call.

AFTP_ENTRY aftp_destroy(
AFTP_HANDLE_TYPE connection_id,
AFTPETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object to be destroyed. This object was originally created with aftp_create().

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE aftp_rc;

    AFTP_HANDLE_TYPE      connection_id;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     *

     * If you have opened a connection with aftp_connect()

     * you must also issue an aftp_close()

     */

     aftp_destroy(connection_id, &aftp_rc);

}

Line Flows

None.


AFTP_DIR_CLOSE
AFTP API Call Reference

AFTP_DIR_CLOSE

Use this call to cancel a directory listing on the AFTP server that is in progress or end a directory listing on the AFTP server after NO_MORE_ENTRIES has been returned from an aftp_dir_read() call. A connection to the AFTP server must be established before using this call. A directory listing on the AFTP server must be started by calling aftp_dir_open() prior to calling this call.

AFTP_ENTRY atp_dir_close(
AFTP_HANDLE_TYPE connection_id,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

See aftp_dir_read for a complete example showing the related calls: aftp_dir_open, aftp_dir_read, and aftp_dir_close.

Line Flows

None.


AFTP_DIR_OPEN
AFTP API Call Reference

AFTP_DIR_OPEN

Use this call to begin a directory listing and specify the file search parameters on the AFTP server. The aftp_dir_read() call is used to read individual directory entries. The aftp_dir_close() call is used to end the directory listing. A connection to the AFTP server must be established before using this call.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_dir_open(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR filespec,
AFTP_LENGTH_TYPE length,
AFTP_FILE_TYPE_TYPE file_type,
AFTP_INFO_LEVEL_TYPE info_level,
unsigned char AFTP_PTR path,
AFTP_LENGTH_TYPE path_buffer_length,
AFTP_LENGTH_TYPE AFTP_PTR path_returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

FILESPEC

(input) The search string which the server uses to generate the directory listing. The files in the listing must match the search string. The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can either be an absolute or relative path name and can contain wildcard characters.

LENGTH

(input) The length of the filespec parameter in bytes.

FILE_TYPE

(input) The type of information (directory names or file names) to be returned.

AFTP_FILE

Only file entries

AFTP_DIRECTORY

Only directory entries

AFTP_ALL_FILES

Both file and directory entries

INFO_LEVEL

(input) The level and format of information to be returned about each file or directory entry.

AFTP_NATIVE_NAMES

Native names without attributes.

AFTP_NATIVE_ATTRIBUTES

Native names and native file attributes.

PATH

(output) The fully qualified directory name in which of all of the directory entries exist. The actual directory entries will be returned when the aftp_dir_read() call is used. The path can be used along with the returned directory entry filename to create a fully qualified pathname to use on another AFTP file call.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

PATH_BUFFER_LENGTH

(input) The size in bytes of the buffer pointed to by the path parameter.

PATH_RETURNED_LENGTH

(output) The number of bytes returned in the path parameter.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

See aftp_dir_read for a complete example showing the related calls: aftp_dir_open, aftp_dir_read, and aftp_dir_close.

Line Flows

Sends a request for a directory listing to the AFTP server and waits for a response which includes the fully specified path of the directory listing or an error indicator. If the path of the directory listing is received, the AFTP server sends all of the directory entries as well. Once the list is complete, a special end-of-list indicator is sent to the AFTP client.


AFTP_DIR_READ
AFTP API Call Reference

AFTP_DIR_READ

Use this call to get an individual directory entry, based upon the search specified on the aftp_dir_open() call. A connection to the AFTP server must be established before using this call. The aftp_dir_open() call must be called prior to listing the directory entries.

AFTP_ENTRY aftp_dir_read(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR dir_entry,
AFTP_LENGTH_TYPE dir_entry_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_BOOLEAN_TYPE AFTP_PTR no_more_entries,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIR_ENTRY

(input) Pointer to a buffer into which the procedure will write the directory entry.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

DIR_ENTRY_SIZE

(input) The size in bytes of the dir_entry buffer.

RETURNED_LENGTH

(output) The number of bytes returned in the dir_entry parameter.

NO_MORE_ENTRIES

(output) Whether or not an entry was returned on this call.

A value of zero indicates that there are more directory entries and that an entry was returned on this call.

A nonzero value indicates that there are no more directory entries and no entry was returned on this call. The returned length parameter will be set to zero. Subsequent calls to aftp_dir_read() will also result in no_more_entries being nonzero. To end the directory listing, your next call should be aftp_dir_close().

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

This example shows how to use the aftp_dir_open, aftp_dir_read, and aftp_dir_close calls together.

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 dir_entry[AFTP_FILE_NAME_SIZE +1];

    AFTP_LENGTH_TYPE              dir_entry_length;

    /* The value used for filespec will vary based on platform:

     *   VM common naming:       filespec="/a/foo*"

     *   VM native naming:       filespec="foo*.*.a"

     *   MVS PDS common naming:  filespec="/user.clist/foo*"

     *   MVS PDS native naming:  filespec="'user.clist(foo*)'"

     *   MVS sequential common:  filespec="/user.qual*.a*.**"

     *   MVS sequential native:  filespec="'user.qual*.a*.**'"

     */

    static unsigned char AFTP_PTR filespec = "/user.clist/foo*";

    unsigned char                 path[AFTP_FILE_NAME_SIZE+1];

    AFTP_LENGTH_TYPE              path_length;

    AFTP_BOOLEAN_TYPE             no_more_entries;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    /*

     * Open a new directory listing on the AFTP server. Both files and

     * directory names will be listed along with their attributes.

     */

    aftp_dir_open(

        connection_id,

        filespec,

        (AFTP_LENGTH_TYPE)strlen(filespec),

        AFTP_DIRECTORY | AFTP_FILE,

        AFTP_NATIVE_ATTRIBUTES,

        path,

        (AFTP_LENGTH_TYPE)sizeof(path)-1,

        &path_length,

        &aftp_rc);

    if (aftp_rc == AFTP_RC_OK) {

        path[path_length] = '\0';

        printf("Directory listing of %s.", path);

        do {

            /*

             * Read one directory entry from the AFTP server

             */

            aftp_dir_read(

                connection_id,

                dir_entry,

                (AFTP_LENGTH_TYPE)sizeof(dir_entry)-1,

                &dir_entry_length,

                &no_more_entries,

                &aftp_rc);

            if (aftp_rc == AFTP_RC_OK && no_more_entries == 0) {

                dir_entry[dir_entry_length] = '\0';

                printf("File: %s\n", dir_entry);

            }

            /*

             * Loop until we either run out of directory

             * entries or an error occurs.

             */

        } while (aftp_rc == AFTP_RC_OK && no_more_entries == 0);

        /*

         * Terminate the directory listing by executing

         * a close.

         */

        aftp_dir_close(connection_id, &aftp_rc);

        if (aftp_rc != AFTP_RC_OK) {

            fprintf(

                stderr,

                "Error closing AFTP directory.\n");

        }

    }

    else {

        fprintf(stderr, "Error opening AFTP directory.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_ALLOCATION_SIZE
AFTP API Call Reference

AFTP_EXTRACT_ALLOCATION_SIZE

Use this call to extract the AFTP file allocation size. If the aftp_set_allocation_size() call has not been invoked, the AFTP default allocation size value is returned.

AFTP_ENTRY aftp_extract_allocation_size(
AFTP_HANDLE_TYPE connection_id,
AFTP_ALLOCATION_SIZE_TYPE AFTP_PTR allocation_size,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

ALLOCATION_SIZE

(output) The allocation size in bytes that had been set for the AFTP file transfer operation.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE           connection_id;

    AFTP_RETURN_CODE_TYPE      aftp_rc;

    AFTP_ALLOCATION_SIZE_TYPE  allocation_size;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    aftp_extract_allocation_size(

        connection_id,

        &allocation_size,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP allocation size.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_BLOCK_SIZE
AFTP API Call Reference

AFTP_EXTRACT_BLOCK_SIZE

Use this call to extract the file block size. If the aftp_set_block_size() call has not been invoked, the AFTP default block size value will be returned.

AFTP_ENTRY aftp_extract_block_size(
AFTP_HANDLE_TYPE connection_id,
AFTP_BLOCK_SIZE_TYPE AFTP_PTR block_size,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

BLOCK_SIZE

(output) The AFTP file block size in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE         connection_id;

    AFTP_RETURN_CODE_TYPE    aftp_rc;

    AFTP_BLOCK_SIZE_TYPE     block_size;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    aftp_extract_block_size(

        connection_id,

        &block_size,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP block size.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_DATA_TYPE
AFTP API Call Reference

AFTP_EXTRACT_DATA_TYPE

Use this call to extract the data type for file transfers. If the aftp_set_data_type() call has not been invoked, the AFTP default data type value is returned.

AFTP_ENTRY aftp_extract_data_type(
AFTP_HANDLE_TYPE connection_id,
AFTP_DATA_TYPE_TYPE AFTP_PTR data_type,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DATA_TYPE

(output) The data type to be used for data transfers.

AFTP_ASCII

Transfer files as text files in ASCII.

AFTP_BINARY

Transfer files as a binary sequence of bytes without translation.

AFTP_DEFAULT_DATA_TYPE

Use the data transfer type set in the INI file. If no type is set in the INI file, use AFTP_ASCII.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE        connection_id;

    AFTP_RETURN_CODE_TYPE   aftp_rc;

    AFTP_DATA_TYPE_TYPE     data_type;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    aftp_extract_data_type(

        connection_id,

        &data_type,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP data type.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_DATE_MODE
AFTP API Call Reference

AFTP_EXTRACT_DATE_MODE

Use this call to extract the way file dates are handled for data transfer. If the aftp_set_date_mode() call has not been invoked, the AFTP default date mode value will be returned.

AFTP_ENTRY aftp_extract_date_mode(
AFTP_HANDLE_TYPE connection_id,
AFTP_DATE_MODE_TYPE AFTP_PTR date_mode,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DATE_MODE

(output) The type of date given to the new file after transfer.

AFTP_NEWDATE

Assign the time/date stamp of the time of transfer.

AFTP_OLDDATE

Assign the time/date stamp of the source file.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE           connection_id;

    AFTP_RETURN_CODE_TYPE      aftp_rc;

    AFTP_DATE_MODE_TYPE        date_mode;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    aftp_extract_date_mode(

        connection_id,

        &date_mode,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP date mode.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_DESTINATION
AFTP API Call Reference

AFTP_EXTRACT_DESTINATION

Use this call to extract the destination of the AFTP server. If the aftp_set_destination() call has not been invoked, the AFTP default destination value will be returned.

AFTP_ENTRY aftp_extract_destination(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR destination,
AFTP_LENGTH_TYPE destination_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with ftp_create().

DESTINATION

(output) Buffer into which the name of the AFTP server is written. This parameter can be either a symbolic destination name or a partner LU name.

See the APPC Application Suite User's Guide for information about specifying destinations in the APPC Application Suite.

DESTINATION_SIZE

(input) The size of the buffer in which the destination will be stored.

Use the AFTP_FQLU_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

RETURNED_LENGTH

(output) The actual length of the destination parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 destname[AFTP_FQLU_NAME_SIZE+1];

    AFTP_LENGTH_TYPE              returned_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the destination name for AFTP.

     */

    aftp_extract_destination(

        connection_id,

        destname,

        (AFTP_LENGTH_TYPE)sizeof(destname)-1,

        &returned_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP destination.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_MODE_NAME
AFTP API Call Reference

AFTP_EXTRACT_MODE_NAME

Use this call to extract the mode name specified for the connection to the AFTP server. If the aftp_set_mode_name() call has not been invoked, the AFTP default mode name value will be returned.

AFTP_ENTRY aftp_extract_mode_name(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR mode_name,
AFTP_LENGTH_TYPE mode_name_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

MODE_NAME

(output) The buffer in which the mode name is to be stored.

Use the AFTP_MODE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

MODE_NAME_SIZE

(input) The size of buffer in which the mode name will be stored.

RETURNED_LENGTH

(output) The actual length of the mode_name parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE                connection_id;

    AFTP_RETURN_CODE_TYPE           aftp_rc;

    unsigned char AFTP_PTR          mode_name[AFTP_MODE_NAME_SIZE+1];

    AFTP_LENGTH_TYPE                returned_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the APPC mode name for AFTP.

     */

    aftp_extract_mode_name(

        connection_id,

        mode_name,

        (AFTP_LENGTH_TYPE)sizeof(mode_name)-1,

        &returned_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP mode name.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_PARTNER_LU_NAME
AFTP API Call Reference

AFTP_EXTRACT_PARTNER_LU_NAME

Use this call to extract the fully qualified LU name of the server. A connection to the AFTP server must occur before this call can be invoked.

AFTP_ENTRY aftp_extract_partner_LU_name(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR partner_LU_name,
AFTP_LENGTH_TYPE partner_LU_name_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

PARTNER_LU_NAME

(output) Buffer to which the fully qualified LU name is written.

Use the AFTP_FQLU_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

PARTNER_LU_NAME_SIZE

(input) The size of the buffer that the partner_LU_name will be written to.

RETURNED_LENGTH

(output) The actual length of the partner_LU_name parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE         connection_id;

    AFTP_RETURN_CODE_TYPE    aftp_rc;

    unsigned char            partner[AFTP_FQLU_NAME_SIZE+1];

    AFTP_LENGTH_TYPE         returned_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    /*

     * Extract the partner LU name for AFTP.

     */

    aftp_extract_partner_LU_name(

        connection_id,

        partner,

        (AFTP_LENGTH_TYPE)sizeof(partner)-1,

        &returned_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP destination.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_PASSWORD
AFTP API Call Reference

AFTP_EXTRACT_PASSWORD

Use this call to extract the password specified for the connection to the AFTP server. If the aftp_set_password() call has not been invoked, the AFTP default password value will be returned.

AFTP_ENTRY aftp_extract_password(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR password,
AFTP_LENGTH_TYPE password_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

PASSWORD

(output) The buffer in which the password used on the connection is written.

Use the AFTP_PASSWORD_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

PASSWORD_SIZE

(input) The size of the buffer in which the password is to be written.

RETURNED_LENGTH

(output) The actual length of the password parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE               connection_id;

    AFTP_RETURN_CODE_TYPE          aftp_rc;

    unsigned char                  password[AFTP_PASSWORD_SIZE+1];

    AFTP_LENGTH_TYPE               returned_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the password for AFTP.

     */

    aftp_extract_password(

        connection_id,

        password,

        (AFTP_LENGTH_TYPE)sizeof(password)-1,

        &returned_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP password.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_RECORD_FORMAT
AFTP API Call Reference

AFTP_EXTRACT_RECORD_FORMAT

Use this call to extract the record format for the data transfer. If the aftp_set_record_format() call has not been invoked, the AFTP default record format value will be returned.

AFTP_ENTRY aftp_extract_record_format(
AFTP_HANDLE_TYPE connection_id,
AFTP_RECORD_FORMAT_TYPE AFTP_PTR record_format,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

RECORD_FORMAT

(output) The record format used for file transfer.

AFTP_DEFAULT_RECORD_FORMAT

Specifies that the system on which the file will be written should use its own default setting for record format. This is the initial setting.

AFTP_V

Variable length record, unblocked.

AFTP_VA

Variable length record, unblocked, ASA print-control characters.

AFTP_VB

Variable length record, blocked.

AFTP_VM

Variable length record, unblocked, machine print-control codes.

AFTP_VS

Variable length record, unblocked, spanned.

AFTP_VBA

Variable length record, blocked, ASA print-control characters.

AFTP_VBM

Variable length record, blocked, machine print-control codes.

AFTP_VBS

Variable length record, blocked, spanned.

AFTP_VSA

Variable length record, unblocked, spanned, ASA print-control characters.

AFTP_VSM

Variable length record, unblocked, spanned, machine print-control codes.

AFTP_VBSA

Variable length record, blocked, spanned, ASA print-control characters.

AFTP_VBSM

Variable length record, blocked, spanned, machine print-control codes.

AFTP_F

Fixed length record, unblocked.

AFTP_FA

Fixed length record, unblocked, ASA print-control characters.

AFTP_FB

Fixed length record, blocked.

AFTP_FM

Fixed length record, unblocked, machine print-control codes.

AFTP_FBA

Fixed length record, blocked, ASA print-control characters.

AFTP_FBM

Fixed length record, blocked, machine print-control codes.

AFTP_FBS

Fixed length record, blocked, standard.

AFTP_FBSM

Fixed length record, blocked, machine print-control codes, standard.

AFTP_FBSA

Fixed length record, blocked, ASA print-control characters, standard.

AFTP_U

Undefined length record.

AFTP_UA

Undefined length record, ASA print control characters.

AFTP_UM

Undefined length record, machine print control codes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE          connection_id;

    AFTP_RETURN_CODE_TYPE     aftp_rc;

    AFTP_RECORD_FORMAT_TYPE   record_format;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the file record format for AFTP.

     */

    aftp_extract_record_format(

        connection_id,

        &record_format,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP record format.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_RECORD_LENGTH
AFTP API Call Reference

AFTP_EXTRACT_RECORD_LENGTH

Use this call to extract the record length for fixed length records, or the maximum possible record length for variable length records used for data transfer. If the aftp_set_record_length() call has not been invoked, the AFTP default record length value will be returned.

AFTP_ENTRY aftp_extract_record_length(
AFTP_HANDLE_TYPE connection_id,
AFTP_RECORD_LENGTH_TYPE AFTP_PTR record_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

RECORD_LENGTH

(output) The record length for the data transfer specified in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE            connection_id;

    AFTP_RETURN_CODE_TYPE       aftp_rc;

    AFTP_RECORD_LENGTH_TYPE     record_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the file record length for AFTP.

     */

    aftp_extract_record_length(

        connection_id,

        &record_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

       fprintf(stderr, "Error extracting AFTP record length.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_SECURITY_TYPE
AFTP API Call Reference

AFTP_EXTRACT_SECURITY_TYPE

Use this call to extract the type of APPC conversation security used. If the aftp_set_security_type() call has not been invoked, the AFTP default security type value will be returned.

AFTP_ENTRY aftp_extract_security_type(
AFTP_HANDLE_TYPE connection_id,
AFTP_SECURITY_TYPE AFTP_PTR security_type,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

SECURITY_TYPE

(output) The security to be used when connecting to the AFTP server.

AFTP_SECURITY_NONE

No APPC conversation security is used.

AFTP_SECURITY_SAME

The local security information determined at login time will be transferred to the AFTP server.

AFTP_SECURITY_PROGRAM

A user ID and password will be sent to be verified by the AFTP server. This security type requires the use of the aftp_set_userid() and aftp_set_password() calls, or the connection attempt will fail.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    AFTP_SECURITY TYPE            sec_type;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the APPC security type for AFTP.

     */

    aftp_extract_security_type(

        connection_id,

        &sec_type,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr,

        "Error extracting AFTP security type.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_TP_NAME
AFTP API Call Reference

AFTP_EXTRACT_TP_NAME

Use this call to extract the transaction program (TP) name of the AFTP server. If the aftp_set_tp_name() call has not been invoked, the AFTP default transaction program name value is returned.

AFTP_ENTRY aftp_extract_tp_name(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR tp_name,
AFTP_LENGTH_TYPE tp_name_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

TP_NAME

(output) The buffer into which the transaction program name of the AFTP server will be written.

Use the AFTP_TP_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

TP_NAME_SIZE

(input) The size of the buffer to which the transaction program name will be written.

RETURNED_LENGTH

(output) The actual length of the transaction program name parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE                connection_id;

    AFTP_RETURN_CODE_TYPE           aftp_rc;

    unsigned char                   tp_name[AFTP_TP_NAME_SIZE+1];

    AFTP_LENGTH_TYPE                returned_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the TP name for AFTP.

     */

    aftp_extract_tp_name(

        connection_id,

        tp_name

        (AFTP_LENGTH_TYPE)sizeof(tp_name)-1,

        &returned_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP TP name.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_TRACE_LEVEL
AFTP API Call Reference

AFTP_EXTRACT_TRACE_LEVEL

Use this call to extract the current trace level setting.

AFTP_ENTRY aftp_extract_trace_level(
AFTP_TRACE_LEVEL_TYPE AFTP_PTR trace_level,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

TRACE_LEVEL

(output) The current setting of the trace level in AFTP. The constants from AFTP_LVL_NO_TRACING to AFTP_LVL_MAX_TRACE_LVL incrementally increase the amount of trace information.

AFTP_LVL_NO_TRACING

No data will be written to the trace log.

AFTP_LVL_API

Traces crossings of the API boundary.

AFTP_LVL_MAX_TRACE_LVL

Provides the maximum amount of trace information.

Other trace levels are reserved for diagnosing problems with the assistance of ###(vendor support)###.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE         rc;

    AFTP_TRACE_LEVEL_TYPE         trace_level;

    /*

     * There are no prerequisite calls for this call.

     */

    aftp_extract_trace_level(&trace_level, &rc);

    if (rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting trace level\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_USERID
AFTP API Call Reference

AFTP_EXTRACT_USERID

Use this call to extract the user ID specified for the connection to the AFTP server. If the CPI-C extract userid function is not supported the AFTP default user ID value will be returned.

AFTP_ENTRY aftp_extract_userid(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR userid,
AFTP_LENGTH_TYPE userid_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

USERID

(output) The buffer into which the user ID used on the connection will be written.

Use the AFTP_USERID_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

USERID_SIZE

(input) The size of the buffer into which the user ID will be written.

RETURNED_LENGTH

(output) The actual length of the userid parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 userid[AFTP_USERID_SIZE+1];

    AFTP_LENGTH_TYPE              returned_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the user ID for AFTP.

     */

    aftp_extract_userid(

        connection_id,

        userid,

        (AFTP_LENGTH_TYPE)sizeof(userid)-1,

        &returned_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting userid.\n");

    }

}

Line Flows

None.


AFTP_EXTRACT_WRITE_MODE
AFTP API Call Reference

AFTP_EXTRACT_WRITE_MODE

Use this call to extract the way that existing files are treated when a data transfer copies to them. If the aftp_set_write_mode() call has not been invoked, the AFTP default write mode value will be returned.

AFTP_ENTRY aftp_extract_write_mode(
AFTP_HANDLE_TYPE connection_id,
AFTP_WRITE_MODE_TYPE AFTP_PTR write_mode,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

WRITE_MODE

(output) The method used to write a file if a copy of the file already exists. If the file does not exist on the target, the new file is created.

AFTP_REPLACE

Transferred file will replace the existing file.

AFTP_APPEND

Transferred file will be appended to the existing file.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE       connection_id;

    AFTP_RETURN_CODE_TYPE  aftp_rc;

    AFTP_WRITE_MODE_TYPE   write_mode;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Extract the file write mode for AFTP.

     */

    aftp_extract_write_mode(

        connection_id,

        &write_mode,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error extracting AFTP write mode.\n");

    }

}

Line Flows

None.


AFTP_FORMAT_ERROR
AFTP API Call Reference

AFTP_FORMAT_ERROR

Use this call to retrieve the current AFTP error information to a text buffer. The AFTP return code for the current error must not be AFTP_RC_HANDLE_NOT_VALID. If the current status is AFTP_RC_OK, and the aftp_format_error() call is invoked, the return_code value output by this call will be AFTP_RC_STATE_CHECK. The aftp_format_error() call should only be invoked when an error has occurred.

AFTP_ENTRY aftp_format_error(
AFTP_HANDLE_TYPE connection_id,
AFTP_DETAIL_LEVEL_TYPE detail_level,
unsigned char AFTP_PTR error_str,
AFTP_LENGTH_TYPE error_str_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DETAIL_LEVEL

(input) The detail in which the error string will describe the AFTP error. These values can be OR'ed together to retrieve specific sets of information. For example, if the primary message and the error log information should be returned, specify (AFTP_DETAIL_RC | AFTP_DETAIL_LOG).

AFTP_DETAIL_RC

The AFTP return code, error category, index and primary error message will be output.

AFTP_DETAIL_SECOND

The AFTP secondary error message will be output.

AFTP_DETAIL_LOG

The error logging information will be output.

AFTP_DETAIL_INFO

The informational message associated with the error will be output.

AFTP_DETAIL_ALL

All of the previous detail levels will be output in the error string.

ERROR_STR

(output) The buffer into which the error information string will be written.

Use the AFTP_MESSAGE_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

ERROR_STR_SIZE

(input) The size of the buffer in which the error information will be written.

RETURNED_LENGTH

(output) The actual length of the error_str parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE        connection_id;

    AFTP_RETURN_CODE_TYPE   aftp_rc;

    unsigned char           error_string[AFTP_MESSAGE_SIZE+1];

    AFTP_LENGTH_TYPE        returned_length;

    /*

     * There are no specific prerequisite calls for this call,

     * but you must issue a call that returns an error return code

     */

    if (aftp_rc != AFTP_RC_OK) {

        /*

         * We had an AFTP error - so let's get

         * the description that corresponds to

         * the error.

         */

        aftp_format_error(

            connection_id,

            AFTP_DETAIL_ALL,

            error_string,

            (AFTP_LENGTH_TYPE)sizeof(error_string)-1,

            &returned_length,

            &aftp_rc);

    }

}

Line Flows

None.


AFTP_GET_DATA_TYPE_STRING
AFTP API Call Reference

AFTP_GET_DATA_TYPE_STRING

Use this call to get a string which corresponds to the input AFTP data type value. This string is available to allow all users of the AFTP API to have consistent strings for each data type. It is not necessary to create an AFTP connection object prior to the invocation of this call.

AFTP_ENTRY aftp_get_data_type_string(
AFTP_DATA_TYPE_TYPE data_type,
unsigned char AFTP_PTR data_type_string,
AFTP_LENGTH_TYPE data_type_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

DATA_TYPE

(input) An AFTP data type value.

AFTP_ASCII

Transfer files as text files in ASCII.

AFTP_BINARY

Transfer files as a binary sequence of bytes without translation.

AFTP_DEFAULT_DATA_TYPE

Use the data transfer type set in the INI file. If no type is set in the INI file, use AFTP_ASCII.

DATA_TYPE_STRING

(output) The buffer into which the data type string will be written.

Use the AFTP_DATA_TYPE_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

DATA_TYPE_SIZE

(input) The size of the buffer into which the data type string will be written.

RETURNED_LENGTH

(output) The actual length of the data_type_string parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 data_type[AFTP_DATA_TYPE_SIZE+1];

    AFTP_LENGTH_TYPE              returned_length;

    /*

     * There are no prerequisite calls for this call.

     */

    /*

     * Get the data type string.

     */

    aftp_get_data_type_string(

        AFTP_ASCII,

        data_type,

        (AFTP_LENGTH_TYPE)sizeof(data_type)-1,

        &returned_length,

        &aftp_rc);

}

Line Flows

None.


AFTP_GET_DATE_MODE_STRING
AFTP API Call Reference

AFTP_GET_DATE_MODE_STRING

Use this call to get a string which corresponds to the input AFTP date mode value. This string is available to allow all users of the AFTP API to have consistent strings for each date mode type. It is not necessary to create an AFTP connection object prior to the invocation of this call.

AFTP_ENTRY aftp_get_date_mode_string(
AFTP_DATE_MODE_TYPE date_mode,
unsigned char AFTP_PTR date_mode_string,
AFTP_LENGTH_TYPE date_mode_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

DATE_MODE

(input) An AFTP date mode value.

AFTP_NEWDATE

Assign the time/date stamp of the time of transfer.

AFTP_OLDDATE

Assign the time/date stamp of the source file.

DATE_MODE_STRING

(output) The buffer into which the date mode string will be written.

Use the AFTP_DATE_MODE_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

DATE_MODE_SIZE

(input) The size of the buffer into which the date mode string will be written.

RETURNED_LENGTH

(output) The actual length of the date_mode_string parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 date_mode[AFTP_DATE_MODE_SIZE+1];

    AFTP_LENGTH_TYPE              returned_length;

    /*

     * There are no prerequisite calls for this call.

     */

    /*

     * Get the date mode string.

     */

    aftp_get_date_mode_string(

        AFTP_OLDDATE,

        date_mode,

        (AFTP_LENGTH_TYPE)sizeof(date_mode)-1,

        &returned_length,

        &aftp_rc);

}

Line Flows

None.


AFTP_GET_RECORD_FORMAT_STRING
AFTP API Call Reference

AFTP_GET_RECORD_FORMAT_STRING

Use this call to get a string which corresponds to the input AFTP record format value. This string is available to allow all users of the AFTP API to have consistent strings for each record format type. It is not necessary to create an AFTP connection object prior to issuing this call.

AFTP_ENTRY aftp_get_record_format_string(
AFTP_RECORD_FORMAT_TYPE record_format,
unsigned char AFTP_PTR record_format_string,
AFTP_LENGTH_TYPE record_format_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

RECORD_FORMAT

(input) An AFTP record format value.

AFTP_DEFAULT_RECORD_FORMAT

Specifies that the system on which the file will be written should use its own default setting for record format. This is the initial setting.

AFTP_V

Variable length record, unblocked.

AFTP_VA

Variable length record, unblocked, ASA print-control characters.

AFTP_VB

Variable length record, blocked.

AFTP_VM

Variable length record, unblocked, machine print-control codes.

AFTP_VS

Variable length record, unblocked, spanned.

AFTP_VBA

Variable length record, blocked, ASA print-control characters.

AFTP_VBM

Variable length record, blocked, machine print-control codes.

AFTP_VBS

Variable length record, blocked, spanned.

AFTP_VSA

Variable length record, unblocked, spanned, ASA print-control characters.

AFTP_VSM

Variable length record, unblocked, spanned, machine print-control codes.

AFTP_VBSA

Variable length record, blocked, spanned, ASA print-control characters.

AFTP_VBSM

Variable length record, blocked, spanned, machine print-control codes.

AFTP_F

Fixed length record, unblocked.

AFTP_FA

Fixed length record, unblocked, ASA print-control characters.

AFTP_FB

Fixed length record, blocked.

AFTP_FM

Fixed length record, unblocked, machine print-controlcodes.

AFTP_FBA

Fixed length record, blocked, ASA print-control characters.

AFTP_FBM

Fixed length record, blocked, machine print-control codes.

AFTP_FBS

Fixed length record, blocked, standard.

AFTP_FBSM

Fixed length record, blocked, machine print-control codes, standard.

AFTP_FBSA

Fixed length record, blocked, ASA print-control characters, standard.

AFTP_U

Undefined length record.

AFTP_UA

Undefined length record, ASA print control characters.

AFTP_UM

Undefined length record, machine print control codes.

RECORD_FORMAT_STRING

(output) The buffer into which the record format string will be written.

Use the AFTP_RECORD_FORMAT_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

RECORD_FORMAT_SIZE

(input) The size of the buffer into which the record format string will be written.

RETURNED_LENGTH

(output) The actual length of the data structure string parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 recfm[AFTP_RECORD_FORMAT_SIZE+1];

    AFTP_LENGTH_TYPE              returned_length;

    /*

     * There are no prerequisite calls for this call.

     */

    /*

     * Get the record format string.

     */

    aftp_get_record_format_string(

        AFTP_F,

        recfm,

        (AFTP_LENGTH_TYPE)sizeof(recfm)-1,

        &returned_length,

        &aftp_rc);

}

Line Flows

None.


AFTP_GET_WRITE_MODE_STRING
AFTP API Call Reference

AFTP_GET_WRITE_MODE_STRING

Use this call to get a string which corresponds to the input AFTP write mode value. This string is available to allow all users of the AFTP API to have consistent strings for each write mode type. It is not necessary to create an AFTP connection object prior to the invocation of this call.

AFTP_ENTRY aftp_get_write_mode_string(
AFTP_WRITE_MODE_TYPE write_mode,
unsigned char AFTP_PTR write_mode_string,
AFTP_LENGTH_TYPE write_mode_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

WRITE_MODE

(input) The method used to write a file if a copy of the file already exists. If the file does not exist on the target, the new file will be created.

AFTP_REPLACE

Transferred file will replace the existing file.

AFTP_APPEND

Transferred file will be appended to the existing file.

WRITE_MODE_STRING

(output) The buffer into which the write mode string will be written.

Use the AFTP_WRITE_MODE_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

WRITE_MODE_SIZE

(input) The size of the buffer into which the write mode string will be written.

RETURNED_LENGTH

(output) The actual length of the write mode string parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 write_mode[AFTP_WRITE_MODE_SIZE+1];

    AFTP_LENGTH_TYPE              returned_length;

    /*

     * There are no prerequisite calls for this call.

     */

    /*

     * Get the write mode string.

     */

    aftp_get_write_mode_string(

        AFTP_REPLACE,

        write_mode

        (AFTP_LENGTH_TYPE)sizeof(write_mode)-1,

        &returned_length,

        &aftp_rc);

}

Line Flows

None.


AFTP_LOAD_INI_FILE
AFTP API Call Reference

AFTP_LOAD_INI_FILE

Use this call to read the AFTP initialization file into memory. The AFTP and ACOPY programs both use the initialization file. This file includes information required to map filenames on the current platform. Once the AFTP initialization file is stored in memory, AFTP will automatically consult the data it contains before proceeding with any operations. It is not necessary to create an AFTP connection object prior to the invocation of this call.

The name of the initialization file varies by operating system:

•	MVS: DD:APPFTPI

•	VM: AFTP INI

•	NT: AFTP.INI

AFTP_ENTRY aftp_load_ini_file(
unsigned char AFTP_PTR filename,
AFTP_LENGTH_TYPE filename_size,
unsigned char AFTP_PTR program_path,
AFTP_LENGTH_TYPE path_size,
unsigned char AFTP_PTR error_string,
AFTP_LENGTH_TYPE error_string_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

FILENAME

(input) The filename of the AFTP initialization file.

FILENAME_SIZE

(input) The length of the filename parameter in bytes.

PROGRAM_PATH

(input) For NT, the fully qualified file specification of the program that is running. The path from the file specification will be used to locate the AFTP initialization file.

For MVS or VM where this information is not available, provide a 0-length string (not a null string) for this parameter.

PATH_SIZE

(input) The length of the program_path parameter in bytes.

ERROR_STRING

(output) The buffer into which any error messages will be written during loading of the initialization file.

Use the AFTP_INI_MESSAGE_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

ERROR_STRING_SIZE

(input) The size of the buffer into which the error information will be written.

RETURNED_LENGTH

(output) The actual size of the error information in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    static unsigned char AFTP_PTR init_file_name = "DD:APPFTPI";

    static unsigned char AFTP_PTR program_name = ""

    unsigned char                 error_string[AFTP_INI_MESSAGE_SIZE+1];

    AFTP_LENGTH_TYPE              returned_length;

    /*

     * There are no prerequisite calls for this call.

     */

    /*

     * Load the AFTP initialization file into memory.

     */

    aftp_load_ini_file(

        init_file_name,

        (AFTP_LENGTH_TYPE)strlen(init_file_name),

        program_name,

        (AFTP_LENGTH_TYPE)strlen(program_name),

        error_string,

        (AFTP_LENGTH_TYPE)sizeof(error_string),

        &returned_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK {

        error_string[returned_length]='\0';

        printf(stderr, error_string);

    }

}

Line Flows

None.


AFTP_LOCAL_CHANGE_DIR
AFTP API Call Reference

AFTP_LOCAL_CHANGE_DIR

Use this call to change the current working directory on the AFTP client. A connection to the AFTP server is not required before using this call.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_local_change_dir(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR directory,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIRECTORY

(input) The new directory name. The format of this name can either be the native syntax on the AFTP client or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The directory specified can either be an absolute or relative path name.

LENGTH

(input) The length of the directory parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /* The value used will vary based on platform:

     *   VM common naming:       directory = "/d"

     *   VM native naming:       directory = "/d"

     *   MVS PDS common naming:  directory = "/user.clist/"

     *   MVS PDS native naming:  directory = "'user.clist'"

     *   MVS data set prefix common:  directory = "/user.qual.a."

     *   MVS data set prefix native:  directory = "'user.qual.a.'"

     *   NT common naming:     directory = "/c:/nt"

     *   NT native naming:     directory = "c:\\nt"

     */

    static unsigned char AFTP_PTR directory = "/user.clist/"; /* MVS */

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Specify the new current working directory name on the AFTP

     * client.

     */

    aftp_local_change_dir(

        connection_id,

        directory,

        (AFTP_LENGTH_TYPE)strlen(directory),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error changing AFTP directory.\n");

    }

}

Line Flows

None.


AFTP_LOCAL_DIR_CLOSE
AFTP API Call Reference

AFTP_LOCAL_DIR_CLOSE

Use this call to cancel a directory listing on the AFTP client that is in progress or end a directory listing on the AFTP client after no_more_entries has been returned from an aftp_local_dir_read() call. A connection to the AFTP server is not required before using this call. A directory listing on the AFTP client must be started by calling aftp_local_dir_open() prior to making this call.

AFTP_ENTRY aftp_local_dir_close(
AFTP_HANDLE_TYPE connection_id,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

See aftp_local_dir_read for a complete example showing the related calls: aftp_local_dir_open, aftp_local_dir_read, and aftp_local_dir_close.

Line Flows

None.


AFTP_LOCAL_DIR_OPEN
AFTP API Call Reference

AFTP_LOCAL_DIR_OPEN

Use this call to begin a directory listing and specify the file search parameters on the AFTP client. The aftp_local_dir_read() call is used to read individual directory entries. The aftp_local_dir_close() call is used to end the directory listing. A connection to the AFTP server is not required before using this call.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_local_dir_open(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR filespec,
AFTP_LENGTH_TYPE length,
AFTP_FILE_TYPE_TYPE file_type,
AFTP_INFO_LEVEL_TYPE info_level,
unsigned char AFTP_PTR path,
AFTP_LENGTH_TYPE path_buffer_length,
AFTP_LENGTH_TYPE AFTP_PTR path_returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

FILESPEC

(input) The search string which the client uses to generate the directory listing. The files in the listing must match the search string. The format of this name can either be the native syntax on the AFTP client or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can either be an absolute or relative path name and can contain wildcard characters.

LENGTH

(input) The length of the filespec parameter in bytes.

FILE_TYPE

(input) The type of information (directory names or file names) to be returned.

AFTP_FILE

Only file entries

AFTP_DIRECTORY

Only directory entries

AFTP_ALL_FILES

Both file and directory entries

INFO_LEVEL

(input) The level and format of information to be returned about each file or directory entry.

AFTP_NATIVE_NAMES

Native names without attributes.

AFTP_NATIVE_ATTRIBUTES

Native names and native file attributes.

PATH

(output) The fully qualified directory name in which of all of the directory entries exist. The actual directory entries will be returned when the aftp_local_dir_read() call is used. The path can be used along with the returned directory entry filename to create a fully qualified path name to use on another AFTP file call.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

PATH_BUFFER_LENGTH

(input) The size in bytes of the buffer pointed to by the path parameter.

PATH_RETURNED_LENGTH

(output) The number of bytes returned in the path parameter.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

See aftp_local_dir_read for a complete example showing the related calls: aftp_local_dir_open, aftp_local_dir_read, and aftp_local_dir_close.

Line Flows

None.


AFTP_LOCAL_DIR_READ
AFTP API Call Reference

AFTP_LOCAL_DIR_READ

Use this call to get an individual directory entry from the AFTP client, based upon the search specified on the aftp_local_dir_open() call. A connection to the AFTP server is not required before using this call. The aftp_local_dir_open() call must be called prior to listing the directory entries.

AFTP_ENTRY aftp_local_dir_read(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR dir_entry,
AFTP_LENGTH_TYPE dir_entry_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_BOOLEAN_TYPE AFTP_PTR no_more_entries,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIR_ENTRY

(input) Pointer to a buffer into which the procedure will write the directory entry.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

DIR_ENTRY_SIZE

(input) The size in bytes of the dir_entry buffer.

RETURNED_LENGTH

(output) The number of bytes returned in the dir_entry parameter.

NO_MORE_ENTRIES

(output) Whether or not an entry was returned on this call.

A value of zero indicates that there are more directory entries and that an entry was returned on this call.

A nonzero value indicates that there are no more directory entries and that no entry was returned on this call. The returned length parameter is set to zero. Subsequent calls to aftp_local_dir_read() will also result in no_more_entries being nonzero. To end the directory listing, your next call should be aftp_local_dir_close().

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    unsigned char                 dir_entry[AFTP_FILE_NAME_SIZE+1];

    AFTP_LENGTH_TYPE              dir_entry_length;

    /* The value used for filespec will vary based on platform:

     *   VM common naming:       filespec="/a/foo*"

     *   VM native naming:       filespec="foo*.*.a"

     *   MVS PDS common naming:  filespec="/user.clist/foo*"

     *   MVS PDS native naming:  filespec="'user.clist(foo*)'"

     *   MVS sequential common:  filespec="/user.qual*.a*.**"

     *   MVS sequential native:  filespec="'user.qual*.a*.**'"

     */

    static unsigned char AFTP_PTR filespec = "/user.clist/foo*";

    unsigned char                 path[AFTP_FILE_NAME_SIZE+1];

    AFTP_LENGTH_TYPE              path_length;

    AFTP_BOOLEAN_TYPE             no_more_entries;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Open a new directory listing on the AFTP client. Both files and

     * directory names will be listed along with their attributes.

     */

    aftp_local_dir_open(

        connection_id,

        filespec,

        (AFTP_LENGTH_TYPE)strlen(filespec),

        AFTP_DIRECTORY | AFTP_FILE,

        AFTP_NATIVE_ATTRIBUTES,

        path,

        (AFTP_LENGTH_TYPE)sizeof(path)-1,

        &path_length,

        &aftp_rc);

    if (aftp_rc == AFTP_RC_OK) {

        path[path_length] = '\0';

        printf("Directory listing of %s.", path);

        do {

            /*

             * Read one directory entry from the AFTP client

             */

            aftp_local_dir_read(

                connection_id,

                dir_entry,

                (AFTP_LENGTH_TYPE)sizeof(dir_entry)-1,

                &dir_entry_length,

                &no_more_entries,

                &aftp_rc);

            if (aftp_rc == AFTP_RC_OK && no_more_entries == 0) {

                dir_entry[dir_entry_length] = '\0';

                printf("Local file: %s\n", dir_entry);

            }

            /*

             * Loop until we either run out of directory

             * entries or an error occurs.

             */

        } while (aftp_rc == AFTP_RC_OK && no_more_entries == 0);

        /*

         * Terminate the directory listing by executing

         * a close.

         */

        aftp_local_dir_close(connection_id, &aftp_rc);

        if (aftp_rc != AFTP_RC_OK) {

            fprintf(

                stderr,

                "Error closing local AFTP directory.\n");

        }

    }

    else {

        fprintf(stderr, "Error opening local AFTP directory.\n");

    }

}

Line Flows

None.


AFTP_LOCAL_QUERY_CURRENT_DIR
AFTP API Call Reference

AFTP_LOCAL_QUERY_CURRENT_DIR

Use this call to query the current working directory on the AFTP client. A connection to the AFTP server is not required before using this call.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_local_query_current_dir(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR directory,
AFTP_LENGTH_TYPE directory_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIRECTORY

(output) The buffer into which the current working directory on the AFTP client will be written.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

DIRECTORY_SIZE

(input) The size in bytes of the directory buffer.

RETURNED_LENGTH

(output) The actual length of the directory parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE        connection_id;

    AFTP_RETURN_CODE_TYPE   aftp_rc;

    unsigned char           directory[AFTP_FILE_NAME_SIZE+1];

    AFTP_LENGTH_TYPE        length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Query the current working directory on the

     * AFTP client.

     */

    aftp_local_query_current_dir(

        connection_id,

        directory,

        (AFTP_LENGTH_TYPE)sizeof(directory)-1,

        &length,

        &aftp_rc);

    directory[length] = '\0';

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error in query of local current directory.\n");

    }

}

Line Flows

None.


AFTP_QUERY_BYTES_TRANSFERRED
AFTP API Call Reference

AFTP_QUERY_BYTES_TRANSFERRED

Use this call to query the total number of bytes transferred after either an aftp_send_file() or aftp_receive_file() call has completed. The number of bytes transferred is valid only after a file transfer operation has completed. A connection to the AFTP server must be established before using this call.

AFTP_ENTRY aftp_query_bytes_transferred(
AFTP_HANDLE_TYPE connection_id,
AFTP_LENGTH_TYPE AFTP_PTR bytes_transferred,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

BYTES_TRANSFERRED

(output) The number of bytes of data transferred during the last send or receive file operation.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE        connection_id;

    AFTP_RETURN_CODE_TYPE   aftp_rc;

    AFTP_LENGTH_TYPE        number_bytes;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     *    completed a send or receive, use:  aftp_send()

     *    or aftp_receive()

     */

    aftp_query_bytes_transferred(

        connection_id,

        &number_bytes,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error getting number bytes transferred.\n");

    } else {

        fprintf(stdout, "Number of bytes %d.\n", (int)number_bytes);

    }

}

Line Flows

None.


AFTP_QUERY_CURRENT_DIR
AFTP API Call Reference

AFTP_QUERY_CURRENT_DIR

Use this call to query the current directory on the AFTP server. A connection to the AFTP server must be established before using this call.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY ftp_query_current_dir(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR directory,
AFTP_LENGTH_TYPE directory_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIRECTORY

(output) The buffer into which the current working directory on the AFTP server will be written.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

DIRECTORY_SIZE

(input) The size in bytes of the directory buffer.

RETURNED_LENGTH

(output) The actual length of the directory parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE         connection_id;

    AFTP_RETURN_CODE_TYPE    aftp_rc;

    unsigned char            directory[AFTP_FILE_NAME_SIZE+1];

    AFTP_LENGTH_TYPE         length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    /*

     * Query the current working directory on the AFTP server.

     */

    aftp_query_current_dir(

        connection_id,

        directory,

        (AFTP_LENGTH_TYPE)sizeof(directory)-1,

        &length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error in query of current directory.\n");

    }

}

Line Flows

The request for the directory name is sent to the AFTP server and the call waits for a response indicating the success or failure of the query current working directory operation. The directory name of the current working directory on the AFTP server will be sent as the response if the query was successful.


AFTP_QUERY_LOCAL_SYSTEM_INFO
AFTP API Call Reference

AFTP_QUERY_LOCAL_SYSTEM_INFO

Use this call to get information about the AFTP client and the computer it is running on. A connection to the AFTP server is not required before using this call.

AFTP_ENTRY aftp_query_local_system_info(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR system_info,
AFTP_LENGTH_TYPE system_info_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

SYSTEM_INFO

(output) Buffer to store a text string describing the operating system and AFTP client version.

Use the AFTP_SYSTEM_INFO_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

SYSTEM_INFO_SIZE

(input) Size in bytes of the system_info parameter.

RETURNED_LENGTH

(output) Number of bytes stored into the system_info parameter.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE         connection_id;

    AFTP_RETURN_CODE_TYPE    aftp_rc;

    unsigned char            system_info[AFTP_FILE_NAME_SIZE+1];

    AFTP_LENGTH_TYPE         system_info_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Query the AFTP client computer for more information.

     */

    aftp_query_local_system_info(

        connection_id,

        system_info,

        (AFTP_LENGTH_TYPE)sizeof(system_info)-1,

        &system_info_length,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error querying AFTP client system.\n");

    }

}

Line Flows

None.


AFTP_QUERY_LOCAL_VERSION
AFTP API Call Reference

AFTP_QUERY_LOCAL_VERSION

Use this call to query the AFTP version number on the AFTP client computer. A connection to the AFTP server is not required before using this call.

AFTP_ENTRY aftp_query_local_version(
AFTP_VERSION_TYPE AFTP_PTR major_version,
AFTP_VERSION_TYPE AFTP_PTR minor_version,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

MAJOR_VERSION

(output) The major version number of the AFTP code on the client computer. For example 5.4, the 5 is the major version number.

MINOR_VERSION

(output) The minor version number of the AFTP code on the client computer. For example 5.4, the 4 is the minor version number.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE     aftp_rc;

    AFTP_VERSION_TYPE         major_version;

    AFTP_VERSION_TYPE         minor_version;

    /*

     * There are no prerequisite calls for this call.

     */

    /*

     * Query the AFTP version number on the

     * AFTP client computer.

     */

    aftp_query_local_version(

        &major_version,

        &minor_version,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error in query of local version.\n");

    }

}

Line Flows

None.


AFTP_QUERY_SYSTEM_INFO
AFTP API Call Reference

AFTP_QUERY_SYSTEM_INFO

Use this call to get information about the AFTP server and the computer it is running on. A connection to the AFTP server must be established before using this call.

AFTP_ENTRY aftp_query_system_info(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR system_info,
AFTP_LENGTH_TYPE system_info_size,
AFTP_LENGTH_TYPE AFTP_PTR returned_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

SYSTEM_INFO

(output) Buffer to store a text string describing the operating system and AFTP server version.

Use the AFTP_SYSTEM_INFO_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

SYSTEM_INFO_SIZE

(input) Size in bytes of the system_info parameter.

RETURNED_LENGTH

(output) Number of bytes stored into the system_info parameter.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE         connection_id;

    AFTP_RETURN_CODE_TYPE    aftp_rc;

    unsigned char            system_info[AFTP_SYSTEM_INFO_SIZE+1];

    AFTP_LENGTH_TYPE         system_info_length;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    /*

     * Query the AFTP server computer for more information.

     */

    aftp_query_system_info(

        connection_id,

        system_info,

        (AFTP_LENGTH_TYPE)sizeof(system_info)-1,

        &system_info_length,

        &aftp_rc);

    system_info[system_info_length] = '\0';

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error querying AFTP server system.\n");

    }

}

Line Flows

The request for the system information is sent to the AFTP server and the call waits for a response indicating the success or failure of the query system information operation. The system information of the AFTP server computer will be sent as the response if the query was successful.


AFTP_RECEIVE_FILE
AFTP API Call Reference

AFTP_RECEIVE_FILE

Use this call to receive a single file from the AFTP server. A connection to the AFTP server must be established before using this call.

AFTP_ENTRY aftp_receive_file(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR local_file,
AFTP_LENGTH_TYPE local_file_length,
unsigned char AFTP_PTR remote_file,
AFTP_LENGTH_TYPE remote_file_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

LOCAL_FILE

(input) The name given to the file received on the AFTP client. The format of this name can either be the native syntax on the AFTP client or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can contain either an absolute or relative path name.

LOCAL_FILE_LENGTH

(input) The length of the local_file_name parameter in bytes.

REMOTE_FILE

(input) The name of the file sent from the AFTP server. The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can contain either an absolute or relative path name.

REMOTE_FILE_LENGTH

(input) The length of the remote_file_name parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE                     connection_id;

    AFTP_RETURN_CODE_TYPE                aftp_rc;

    /* The value used for filespec will vary based on platform:

     *   VM common naming:       filespec="/a/myfile.dat"

     *   VM native naming:       filespec="myfile.dat.a"

     *   MVS PDS common naming:  filespec="/user.mypds/myfile"

     *   MVS PDS native naming:  filespec="'user.mypds(myfile)'"

     *   MVS sequential common:  filespec="/user.qual.myfile"

     *   MVS sequential native:  filespec="'user.qual.myfile'"

     */

    static unsigned char AFTP_PTR local_file = "/user.mypos/myfile";

    /* MVS */

        static unsigned char AFTP_PTR remote_file = "/a/myfile.dat";

    /* VM */

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    aftp_receive_file(

        connection_id,

        local_file,

        (AFTP_LENGTH_TYPE)strlen(local_file),

        remote_file,

        (AFTP_LENGTH_TYPE)strlen(remote_file),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error receiving AFTP file.\n");

    }

}

Line Flows

The request to receive the file(s) is sent to the AFTP server. A send file indicator will be returned to the AFTP client. All records of each file are then sent from the AFTP server to the AFTP client.


AFTP_REMOVE_DIR
AFTP API Call Reference

AFTP_REMOVE_DIR

Use this call to remove a directory from the AFTP server. A connection to the AFTP server must be established before using this call.

PLATFORM DIFFERENCES:

1.	On VM, this call is not supported. If issued, the call will fail with return code AFTP_RC_FAIL_NO_RETRY.

2.	On MVS, partitioned data sets act as the directory structure. This call will delete a partitioned data set with the name specified.

Read the APPC Application Suite User's Guide for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_remove_dir(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR directory,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DIRECTORY

(input) The directory to be removed. The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The directory specified can be either an absolute or relative path name.

LENGTH

(input) The length of the directory parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE                     connection_id;

    AFTP_RETURN_CODE_TYPE                aftp_rc;

    /* The value used for filespec will vary based on platform:

     *   VM  not supported

     *   MVS PDS common naming:  directory="/user.clist/"

     *   MVS PDS native naming:  directory="'user.clist'"

     */

    static unsigned char AFTP_PTR directory = "/user.clist/";

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    aftp_remove_dir(

        connection_id,

        directory,

        (AFTP_LENGTH_TYPE)strlen(directory),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error removing AFTP directory.\n");

    }

}

Line Flows

The remove directory request and the directory name to remove are sent to the AFTP server and the call waits for a response indicating the success or failure of the remove directory operation.


AFTP_RENAME
AFTP API Call Reference

AFTP_RENAME

Use this call to rename a file on the AFTP server. A connection to the AFTP server must be established before using this call.

AFTP_ENTRY aftp_rename(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR oldfile,
AFTP_LENGTH_TYPE oldlength,
unsigned char AFTP_PTR newfile,
AFTP_LENGTH_TYPE newlength,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

OLDFILE

(input) The name of the file to be renamed.

The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can either be an absolute or relative path name.

OLDLENGTH

(input) The length in bytes of the oldfile parameter.

NEWFILE

(input) The new name of the file.

The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can either be an absolute or relative path name.

NEWLENGTH

(input) The length in bytes of the newfile parameter.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /* The value used for filespec will vary based on platform:

     *   VM common naming:       newfile="/a/foo.file"

     *   VM native naming:       newfile="foo.file.a"

     *   MVS PDS common naming:  newfile="/user.clist/foo"

     *   MVS PDS native naming:  newfile="'user.clist(foo)'"

     *   MVS sequential common:  newfile="/user.qual.a.foo"

     *   MVS sequential native:  newfile="'user.qual.a.foo'"

     */

    static unsigned char AFTP_PTR newfile = "/user.clist/foo";

    static unsigned char AFTP_PTR oldfile = "/user.clist/abc";

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    aftp_rename(

        connection_id,

        oldfile,

        (AFTP_LENGTH_TYPE)strlen(oldfile),

        newfile,

        (AFTP_LENGTH_TYPE)strlen(newfile),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error renaming AFTP file.\n");

    }

}

Line Flows

The rename request, old, and new file names are sent to the AFTP server and the call waits for a response indicating the success or failure of the rename operation.


AFTP_SEND_FILE
AFTP API Call Reference

AFTP_SEND_FILE

Use this call to send a single file to the AFTP server. A connection to the AFTP server must be established before using this call.

AFTP_ENTRY aftp_send_file(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR local_file,
AFTP_LENGTH_TYPE local_file_length,
unsigned char AFTP_PTR remote_file,
AFTP_LENGTH_TYPE remote_file_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

LOCAL_FILE

(input) The name of the file sent from the AFTP client. The format of this name can either be the native syntax on the AFTP client or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can contain either an absolute or relative path name.

LOCAL_FILE_LENGTH

(input) The length of the local_file_name parameter in bytes.

REMOTE_FILE

(input) The name given to the file received on the AFTP server. The format of this name can either be the native syntax on the AFTP server or the AFTP common naming convention (described in the APPC Application Suite User's Guide). The file specified can contain either an absolute or relative path name.

REMOTE_FILE_LENGTH

(input) The length of the remote_file_name parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE                     connection_id;

    AFTP_RETURN_CODE_TYPE                aftp_rc;

    /* The value used for filespec will vary based on platform:

     *   VM common naming:       filespec="/a/myfile.dat"

     *   VM native naming:       filespec="myfile.dat.a"

     *   MVS PDS common naming:  filespec="/user.mypds/myfile"

     *   MVS PDS native naming:  filespec="'user.mypds(myfile)'"

     *   MVS sequential common:  filespec="/user.qual.myfile"

     *   MVS sequential native:  filespec="'user.qual.myfile'"

     */

    static unsigned char AFTP_PTR local_file = "/user.mypos/myfile";

    /* MVS */

        static unsigned char AFTP_PTR remote_file = "/a/myfile.dat";

    /* VM */

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:         aftp_create()

     *    a connection to server, use:  aftp_connect()

     */

    aftp_send_file(

        connection_id,

        local_file,

        (AFTP_LENGTH_TYPE)strlen(local_file),

        remote_file,

        (AFTP_LENGTH_TYPE)strlen(remote_file),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error sending AFTP file.\n");

    }

}

Line Flows

The send file request is sent to the AFTP server, immediately followed by all records of the files. The call waits for a response indicating the success or failure of the send file operation.


AFTP_SET_ALLOCATION_SIZE
AFTP API Call Reference

AFTP_SET_ALLOCATION_SIZE

Use this call to set the AFTP file allocation size. A connection to the AFTP server is not required before using this call. The file allocation size can be changed at any time.

AFTP_ENTRY aftp_set_allocation_size(
AFTP_HANDLE_TYPE connection_id,
AFTP_ALLOCATION_SIZE_TYPE allocation_size,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

ALLOCATION_SIZE

(input) The allocation size in bytes to set for the AFTP file. The default allocation size value is 0.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE         connection_id;

    AFTP_RETURN_CODE_TYPE    aftp_rc;

   /*

    * Before issuing the example call, you must have:

    *    a connection_id, use:  aftp_create()

    */

   /*

    * Set the file allocation size for AFTP file

    * transfers.

    */

    aftp_set_allocation_size(

        connection_id,

        500,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP allocation size.\n");

    }

}

Line Flows

None.


AFTP_SET_BLOCK_SIZE
AFTP API Call Reference

AFTP_SET_BLOCK_SIZE

Use this call to set the file block size. A connection to the AFTP server is not required before using this call. The file block size may be changed at any time.

AFTP_ENTRY aftp_set_block_size(
AFTP_HANDLE_TYPE connection_id,
AFTP_BLOCK_SIZE block_size,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

BLOCK_SIZE

(input) The AFTP file block size in bytes. The default block size value is 0.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE         connection_id;

    AFTP_RETURN_CODE_TYPE   aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Set the file block size for AFTP file

     * transfers.

     */

    aftp_set_block_size(

        connection_id,

        512,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP block size.\n");

    }

}

Line Flows

None.


AFTP_SET_DATA_TYPE
AFTP API Call Reference

AFTP_SET_DATA_TYPE

Use this call to set the data type for file transfers. A connection to the AFTP server is not required before using this call. The data type can be changed at any time.

AFTP_ENTRY aftp_set_data_type(
AFTP_HANDLE_TYPE connection_id
AFTP_DATA_TYPE_TYPE data_type,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DATA_TYPE

(input) The data type to be used for subsequent data transfers.

AFTP_ASCII

Transfer files as text files in ASCII.

AFTP_BINARY

Transfer files as a binary sequence of bytes without translation.

AFTP_DEFAULT_DATA_TYPE

Use the data transfer type set in the INI file. If no type is set in the INI file, use AFTP_ASCII.

This is the default setting.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE       connection_id;

    AFTP_RETURN_CODE_TYPE  aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Set the data type for AFTP file

     * transfers.

     */

    aftp_set_data_type(

        connection_id,

        AFTP_BINARY,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP data type.\n");

    }

}

Line Flows

None.


AFTP_SET_DATE_MODE
AFTP API Call Reference

AFTP_SET_DATE_MODE

Use this call to set the way file dates are handled during data transfer. A connection to the AFTP server is not required before using this call. The date mode can be changed at any time.

AFTP_ENTRY aftp_set_date_mode(
AFTP_HANDLE_TYPE connection_id
AFTP_DATE_MODE_TYPE date_mode,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DATE_MODE

(input) Specifies the way file dates are handled during data transfer.

AFTP_NEWDATE

Assign the time/date stamp of the time of transfer.

AFTP_OLDDATE

Assign the time/date stamp of the source file. This is the default.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE        connection_id;

    AFTP_RETURN_CODE_TYPE   aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Set the date mode for AFTP file

     * transfers.

     */

    aftp_set_date_mode(

        connection_id,

        AFTP_OLDDATE,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP date mode.\n");

    }

}

Line Flows

None.


AFTP_SET_DESTINATION
AFTP API Call Reference

AFTP_SET_DESTINATION

Use this call to specify the destination of the AFTP server. This call must be issued prior to establishing a connection to the AFTP server. After a connection is established, the destination cannot be changed.

AFTP_ENTRY aftp_set_destination(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR destination,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

DESTINATION

(input) Identifies the location of the AFTP server. This parameter can be either a symbolic destination name or a partner LU name.

See the APPC Application Suite User's Guide for information about specifying destinations in the APPC Application Suite.

LENGTH

(input) The length of the destination parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    static unsigned char AFTP_PTR destination = "NETWORK.SERVER";

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     *

     * You cannot have an open connection.

     */

    /*

     * Set the partner we want to communicate with - who will

     * be running the AFTP server.

     */

    aftp_set_destination(

        connection_id,

        destination,

        (AFTP_LENGTH_TYPE)strlen(destination),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP destination.\n");

    }

}

Line Flows

None.


AFTP_SET_MODE_NAME
AFTP API Call Reference

AFTP_SET_MODE_NAME

Use this call to specify the mode name for the connection to the AFTP server. This call can only be invoked prior to the establishment of a connection to the AFTP server. Once a connection is open, the mode name cannot be changed.

AFTP_ENTRY aftp_set_mode_name(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR mode_name,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

MODE_NAME

(input) Specifies the mode name to be used on the connection. The default is #BATCH. The mode name must be 1-8 bytes in length.

LENGTH

(input) The length of the mode_name parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    static unsigned char AFTP_PTR mode_name = "#INTER";

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     *

     * You cannot have an open connection.

     */

    /*

     * Set the mode name for the AFTP connection.

     */

    aftp_set_mode_name(

        connection_id,

        mode_name,

        (AFTP_LENGTH_TYPE)strlen(mode_name),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP mode name.\n");

    }

}

Line Flows

None.


AFTP_SET_PASSWORD
AFTP API Call Reference

AFTP_SET_PASSWORD

Use this call to specify the password for the connection to the AFTP erver. This call can only be invoked prior to the establishment of a connection to the AFTP server. Once a connection is open, the password cannot be changed. If a password is set, a user ID also must be set using aftp_set_userid() before connecting to the AFTP server. Use of this call sets the security type to AFTP_SECURITY_PROGRAM.

AFTP_ENTRY aftp_set_password(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR password,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

PASSWORD

(input) The password to be used on the connection. The password can be 1-8 bytes long.

LENGTH

(input) The length of the password parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    static unsigned char AFTP_PTR password = "MYPASS";

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     *

     * You cannot have an open connection.

     */

    /*

     * Set the password for the AFTP connection.

     */

    aftp_set_password(

        connection_id,

        password,

        (AFTP_LENGTH_TYPE)strlen(password),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP password.\n");

    }

}

Line Flows

None.


AFTP_SET_RECORD_FORMAT
AFTP API Call Reference

AFTP_SET_RECORD_FORMAT

Use this call to set the record format for the data transfer. A connection to the AFTP server is not required before using this call. The record format may be changed at any time.

AFTP_ENTRY atp_set_record_format(
AFTP_HANDLE_TYPE connection_id,
AFTP_RECORD_FORMAT_TYPE record_format,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

RECORD_FORMAT

(input) The record format used for file transfer.

ATP_DEFAULT_RECORD_FORMAT

Specifies that the system on which the file will be written should use its own default setting for record format. This is the initial setting.

AFTP_V

Variable length record, unblocked. This is the default.

AFTP_VA

Variable length record, unblocked, ASA print-control characters.

AFTP_VB

Variable length record, blocked.

AFTP_VM

Variable length record, unblocked, machine print-control codes.

AFTP_VS

Variable length record, unblocked, spanned.

AFTP_VBA

Variable length record, blocked, ASA print-control characters.

AFTP_VBM

Variable length record, blocked, machine print-control codes.

AFTP_VBS

Variable length record, blocked, spanned.

AFTP_VSA

Variable length record, unblocked, spanned, ASA print-control characters.

AFTP_VSM

Variable length record, unblocked, spanned, machine print-control codes.

AFTP_VBSA

Variable length record, blocked, spanned, ASA print-control characters.

AFTP_VBSM

Variable length record, blocked, spanned, machine print-control codes.

AFTP_F

Fixed length record, unblocked.

AFTP_FA

Fixed length record, unblocked, ASA print-control characters.

AFTP_FB

Fixed length record, blocked.

AFTP_FM

Fixed length record, unblocked, machine print-control codes.

AFTP_FBA

Fixed length record, blocked, ASA print-control characters.

AFTP_FBM

Fixed length record, blocked, machine print-control codes.

AFTP_FBS

Fixed length record, blocked, standard.

AFTP_FBSM

Fixed length record, blocked, machine print-control codes, standard.

AFTP_FBSA

Fixed length record, blocked, ASA print-control characters, standard.

AFTP_U

Undefined length record.

AFTP_UA

Undefined length record, ASA print control characters.

AFTP_UM

Undefined length record, machine print control codes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE       connection_id;

    AFTP_RETURN_CODE_TYPE  aftp_rc;

    /*

     * Before issuing the example call, you must have:

     * a connection_id, use:  aftp_create()

     */

    /*

     * Set the record format value for the file transfer.

     */

    aftp_set_record_format(

        connection_id,

        AFTP_VSA,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP record format.\n");

    }

}

Line Flows

None.


AFTP_SET_RECORD_LENGTH
AFTP API Call Reference

AFTP_SET_RECORD_LENGTH

Use this call to set the record length for fixed length records, or the maximum possible record length for variable length records used for data transfer. A connection to the AFTP server is not required before using this call. The record length may be changed at any time.

AFTP_ENTRY aftp_set_record_length(
AFTP_HANDLE_TYPE connection_id,
AFTP_RECORD_LENGTH_TYPE record_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

RECORD_LENGTH

(input) The record length for the data transfer specified in bytes. The default value is 0.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE       connection_id;

    AFTP_RETURN_CODE_TYPE  aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Set the record length for the file transfer.

     */

    aftp_set_record_length(

        connection_id,

        64,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP record length.\n");

    }

}

Line Flows

None.


AFTP_SET_SECURITY_TYPE
AFTP API Call Reference

AFTP_SET_SECURITY_TYPE

Use this call to specify the type of APPC conversation security to be used. This call can only be invoked prior to the establishment of a connection to the AFTP server. Once a connection is open, the APPC security type cannot be changed. If AFTP_SECURITY_PROGRAM is used for the security type a user ID and password also must be set using aftp_set_userid() and aftp_set_password(), before connecting to the AFTP server.

AFTP_ENTRY aftp_set_security_type(
AFTP_HANDLE_TYPE connection_id,
AFTP_SECURITY_TYPE security_type,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

SECURITY_TYPE

(input) The security to be used when connecting to the AFTP server.

AFTP_SECURITY_NONE

No APPC conversation security is used. This is the default unless CPI-C side information is set otherwise.

AFTP_SECURITY_SAME

The local security information determined at login time will be transferred to the AFTP server.

AFTP_SECURITY_PROGRAM

A user ID and password will be sent to be verified by the AFTP server. This security type requires the use of the aftp_set_userid() and aftp_set_password() calls, or the connection attempt will fail.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE       connection_id;

    AFTP_RETURN_CODE_TYPE  aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     *

     * You cannot have an open connection.

     */

    /*

     * Set the APPC conversation security type for the

     * AFTP connection.

     */

    aftp_set_security_type(

        connection_id,

        AFTP_SECURITY_SAME,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP security type.\n");

    }

}

Line Flows

None.


AFTP_SET_TP_NAME
AFTP API Call Reference

AFTP_SET_TP_NAME

Use this call to specify the transaction program (TP) name of the AFTP server. This call can only be invoked prior to the establishment of a connection to the AFTP server. Once a connection is open, the transaction program name cannot be changed. The AFTP API defaults the transaction program name on the server to be AFTPD. This call is not necessary unless you want to experiment with a server which may not have the same behavior as AFTPD.

AFTP_ENTRY aftp_set_tp_name(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR tp_name,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

TP_NAME

(input) The transaction program name of the AFTP server. The transaction program name can be 1-64 bytes long. The default transaction program name is AFTPD.

LENGTH

(input) The length of the transaction program name parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    static unsigned char AFTP_PTR tp_name = "AFTPME";

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     *

     * You cannot have an open connection.

     */

    /*

     * Set the TP name for the AFTP server.

     */

    aftp_set_tp_name(

        connection_id,

        tp_name,

        (AFTP_LENGTH_TYPE)strlen(tp_name),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP TP name.\n");

    }

}

Line Flows

None.


AFTP_SET_TRACE_FILENAME
AFTP API Call Reference

AFTP_SET_TRACE_FILENAME

Use this call to set the name of the file to which trace information will be written. If trace is turned on by the aftp_set_trace_level() call and the aftp_set_trace_filename() call is not issued, the trace file generated will be:

•	On VM:  ASUITE TRC

•	On MVS:  DD:SYSOUT

•	On NT:  ASUITE.TRC

AFTP_ENTRY aftp_set_trace_filename(
unsigned char AFTP_PTR filename,
AFTP_LENGTH_TYPE filename_length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

FILENAME

(input) The name of the file to be used for trace output.

FILENAME_LENGTH

(input) The length of the filename parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_RETURN_CODE_TYPE      rc;

    /* The value used for filespec will vary based on platform:

     *   VM common naming:       filename="/a/aftp.trace"

     *   VM native naming:       filename="aftp.trace.a"

     *   MVS PDS common naming:  filename="/user.clist/aftptrac"

     *   MVS PDS native naming:  filename="'user.clist(aftptrac)'"

     *   MVS sequential common:  filename="/user.qual.a.aftptrac"

     *   MVS sequential native:  filename="'user.qual.a.aftptrac'"

     */

    static unsigned char AFTP_PTR filename = "/user.clist/aftptrac";

    /*

     * There are no prerequisite calls for this call.

     */

    aftp_set_trace_filename(

        filename,

        (AFTP_LENGTH_TYPE)strlen(filename),

        &rc);

    if (rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting tracing filename\n");

    }

}

Line Flows

None.


AFTP_SET_TRACE_LEVEL
AFTP API Call Reference

AFTP_SET_TRACE_LEVEL

Use this call to set the level of tracing to use for AFTP activities. The new trace level will take effect immediately upon making this call. The trace output will be captured in the file specified in the aftp_set_trace_filename() call, which must be issued before this call.

AFTP_ENTRY aftp_set_trace_level(
AFTP_TRACE_LEVEL_TYPE trace_level,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

TRACE_LEVEL

(input) The amount of trace information to be generated. The constants from AFTP_LVL_NO_TRACING to AFTP_LVL_MAX_TRACE_LVL incrementally increase the amount of trace information.

AFTP_LVL_NO_TRACING

No data will be written to the trace log.

AFTP_LVL_API

Traces crossings of the API boundary.

AFTP_LVL_MAX_TRACE_LVL

Provides the maximum amount of trace information.

Other trace levels are reserved for diagnosing problems with the assistance of ###(vendor support)###.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    /*

     * The following calls must be issued here:

     *    aftp_set_trace_filename()

     */

    /*

     * Turn on the tracing.

     */

    aftp_set_trace_level(trace_level, &rc);

    if (rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting the trace level\n");

    }

}

Line Flows

None.


AFTP_SET_USERID
AFTP API Call Reference

AFTP_SET_USERID

Use this call to specify the user ID for the connection to the AFTP server. This call can only be invoked prior to the establishment of a connection to the AFTP server. Once a connection is open, the user ID cannot be changed. If a user ID is set, a password also must be set using aftp_set_password() before connecting to the AFTP server. Use of this call sets the security type to AFTP_SECURITY_PROGRAM.

AFTP_ENTRY aftp_set_userid(
AFTP_HANDLE_TYPE connection_id,
unsigned char AFTP_PTR userid,
AFTP_LENGTH_TYPE length,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

USERID

(input) The user ID to be used on the connection. The user ID can be 1-8 bytes long.

LENGTH

(input) The length of the userid parameter in bytes.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE              connection_id;

    static unsigned char AFTP_PTR userid = "LBONANNO";

    AFTP_RETURN_CODE_TYPE         aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     *

     * You cannot have an open connection.

     */

    /*

     * Set the user ID for the AFTP connection.

     */

    aftp_set_userid(

        connection_id,

        userid,

        (AFTP_LENGTH_TYPE)strlen(userid),

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting user ID.\n");

    }

}

Line Flows

None.


AFTP_SET_WRITE_MODE
AFTP API Call Reference

AFTP_SET_WRITE_MODE

Use this call to set the way existing files will be handled during data transfer. A connection to the AFTP server is not required before using this call. The write mode may be changed at any time.

AFTP_ENTRY aftp_set_write_mode(
AFTP_HANDLE_TYPE connection_id,
AFTP_WRITE_MODE_TYPE write_mode,
AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

CONNECTION_ID

(input) An AFTP connection object originally created with aftp_create().

WRITE_MODE

(input) The method used to write a file if a copy of the file already exists. If the file does not exist on the target, the new file will be created.

AFTP_REPLACE

Transferred file will replace the existing file. This is the default.

AFTP_APPEND

Transferred file will be appended to the existing file.

RETURN_CODE

(output) See Chapter 3, "AFTP Return Codes" for the list of possible return codes.

Example

{

    AFTP_HANDLE_TYPE       connection_id;

    AFTP_RETURN_CODE_TYPE  aftp_rc;

    /*

     * Before issuing the example call, you must have:

     *    a connection_id, use:  aftp_create()

     */

    /*

     * Set the write mode for the AFTP

     * file transfer.

     */

    aftp_set_write_mode(

        connection_id,

        AFTP_REPLACE,

        &aftp_rc);

    if (aftp_rc != AFTP_RC_OK) {

        fprintf(stderr, "Error setting AFTP write mode.\n");

    }

}

Line Flows

None.


CHAPTER 3. AFTP Return Codes
CHAPTER 3

AFTP Return Codes

These are the possible return codes that can be issued for each AFTP API call.

AFTP_RC_BUFFER_TOO_SMALL

The buffer supplied by the caller for output data was too small to hold the data.

AFTP_RC_COMM_CONFIG_LOCAL

The call failed due to a local configuration error. Communications will fail until the configuration problem is resolved.

AFTP_RC_COMM_CONFIG_REMOTE

The call failed due to a remote configuration error. Communications will fail until the configuration problem is resolved.

AFTP_RC_COMM_FAIL_NO_RETRY

The call failed due to a communications problem. The call will not successfully complete using the current parameters.

AFTP_RC_COMM_FAIL_RETRY

The call failed due to a communications problem. The call may successfully complete if tried again.

AFTP_RC_FAIL_FATAL

A serious system error has occurred; no calls can complete successfully.

AFTP_RC_FAIL_INPUT_ERROR

The call may successfully complete after new input parameters are supplied.

AFTP_RC_FAIL_NO_RETRY

The call will not successfully complete using the current parameters.

AFTP_RC_FAIL_RETRY

The call may successfully complete if tried again.

AFTP_RC_HANDLE_NOT_VALID

The call failed because the AFTP connection object passed into the AFTP API was not valid.

AFTP_RC_OK

The call completed successfully.

AFTP_RC_PARAMETER_CHECK

The call failed due to an error in one of the parameters passed into the AFTP API.

AFTP_RC_PROGRAM_INTERNAL_ERROR

The call failed due to a programming error.

AFTP_RC_SECURITY_NOT_VALID

The call failed because of APPC security.

AFTP_RC_STATE_CHECK

The call failed because the current AFTP API call was made when AFTP was not in the correct state required for the current call. For example, you will get a state check error if you try to use aftp_format_error() when no error has occurred.


APPENDIX A. Entry Point Mappings
Appendix A	Entry Point Mappings

Table 5. AFTP API Call Mappings

CALL NAME	ENTRY POINT
aftp_change_dir	ftcd
aftp_close	ftclose
aftp_connect	ftconn
aftp_create	ftcreate
aftp_create_dir	ftcrtdir
aftp_delete	ftdel
aftp_destroy	ftdestry
aftp_dir_close	ftdircls
aftp_dir_open	ftdiropn
aftp_dir_read	ftdirrd
aftp_extract_allocation_size	fteas
aftp_extract_block_size	ftebs
aftp_extract_data_type	ftedt
aftp_extract_date_mode	ftedm
aftp_extract_destination	ftedst
aftp_extract_mode_name	ftemn
aftp_extract_partner_LU_name	fteplu
aftp_extract_password	ftepw
aftp_extract_record_format	fterf
aftp_extract_record_length	fterl
aftp_extract_security_type	ftest
aftp_extract_tp_name	ftetpn
aftp_extract_trace_level	ftetl
aftp_extract_userid	fteui
aftp_extract_write_mode	ftewm
aftp_format_error	ftfe
aftp_get_data_type_string	ftgdts
aftp_get_date_mode_string	ftgdms
aftp_get_record_format_string	ftgrfs
aftp_get_write_mode_string	ftgwms
aftp_load_ini_file	ftlif
aftp_local_change_dir	ftlcd
aftp_local_dir_close	ftldc
aftp_local_dir_open	ftldo
aftp_local_dir_read	ftldr
aftp_local_query_current_dir	ftlqcd
aftp_query_bytes_transferred	ftqbt
aftp_query_current_dir	ftqcd
aftp_query_local_system_info	ftqlsi
aftp_query_local_version	ftqlv
aftp_query_system_info	ftqsys
aftp_receive_file	ftrecv
aftp_remove_dir	ftrd
aftp_rename	ftren
aftp_send_file	ftsend
aftp_set_allocation_size	ftsas
aftp_set_block_size	ftsbs
aftp_set_data_type	ftsdt
aftp_set_date_mode	ftsdm
aftp_set_destination	ftsdest
aftp_set_mode_name	ftsmn
aftp_set_password	ftsp
aftp_set_record_format	ftsrp
aftp_set_record_length	ftsrl
aftp_set_security_type	ftsst
aftp_set_tp_name	ftstp
aftp_set_trace_filename	ftstf
aftp_set_trace_level	ftstl
aftp_set_userid	ftsu
aftp_set_write_mode	ftswm


APPENDIX B Sample Program for AFTP API
Appendix B

Sample Program for AFTP API

PROGRAM:  AFTP Sample Code

COPYRIGHTS:

This module contains code made available by Microsoft Corporation on an AS IS basis. Any one receiving the module is considered to be licensed under Microsoft copyrights to use the Microsoft -provided source code in any way he or she deems fit, including copying it, compiling it, modifying it, and redistributing it, with or without modifications. No license under any Microsoft patents or patent applications is to be implied from this copyright license.

A user of the module should understand that Microsoft cannot provide technical support for the module and will not be responsible for any consequences of use of the program.

Purpose: An example program to show a simple exercise of using the AFTP programming interface

Function: Gets a single file from a remote machine. The user must know the machine name and the file name.

System include files

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

AFTP API include file

Note  If you want to use the header file as it was shipped, change this include statement to appfftp.h. Otherwise, rename the member appfftp.h to aftpapi.h for consistency with other platforms.

#include "aftpapi.h"

int main(int argc, char *argv[])

{

    AFTP_HANDLE_TYPE connection_id;    /* connection id               */

    AFTP_RETURN_CODE_TYPE aftp_rc;     /* return code                 */

    AFTP_SECURITY_TYPE sec_type;       /* security type               */

    unsigned char * LU_name;           /* partner LU name             */

    unsigned char * srcfilename;       /* source file name            */

    unsigned char * destfilename;      /* destination file name       */

printf( "\n" );

if( argc != 4 ) {

    printf( "Usage : aget <LU name> <source filename>"  \

            " <destination filename> \n");

    exit( -1 );

}

LU_name = argv[1];

srcfilename = argv[2];

destfilename = argv[3];

Create the connection object

aftp_create ( connection_id, &aftp_rc );

if ( aftp_rc != AFTP_RC_OK ) {

      printf ( "Error creating connection object.\n" );

      exit ( -1 );

}

Set the partner LU name as the destination.

aftp_set_destination (

        connection_id,

        (unsigned char AFTP_PTR)LU_name,

        (AFTP_LENGTH_TYPE)strlen ( LU_name ),

        &aftp_rc );

if( aftp_rc != AFTP_RC_OK ) {

     printf ( "Error setting the destination.\n" );

     exit ( -1 );

}

Set the security to NONE unless you need security.

aftp_set_security_type (

        connection_id,

        AFTP_SECURITY_NONE,

        &aftp_rc );

if ( aftp_rc == AFTP_RC_OK ) {

     printf ( "Setting security type to NONE.\n" );

} else {

     printf ( "Error setting security type.\n" );

}

Establish a connection with AFTPD server.

aftp_connect ( connection_id, &aftp_rc );

if ( aftp_rc != AFTP_RC_OK ) {

     printf ( "Error establishing the connection.\n" );

     exit ( -1 );

}

Set up file transfer mode.

aftp_set_write_mode (

       connection_id,

       AFTP_REPLACE,

       &aftp_rc );

if ( aftp_rc != AFTP_RC_OK ) {

      printf ( "Error setting write mode.\n" );

}

Extract the security type and display it.

aftp_extract_security_type (

       connection_id,

       &sec_type,

       &aftp_rc );

if ( aftp_rc == AFTP_RC_OK ) {

      printf ( "Security type is : %lu\n", sec_type );

} else {

      printf ( "Error extracting security type.\n" );

}

Transfer the file from the server to the client.

aftp_receive_file (

        connection_id,

        (unsigned char AFTP_PTR)destfilename,

        (AFTP_LENGTH_TYPE)strlen ( destfilename ),

        (unsigned char AFTP_PTR)srcfilename,

        (AFTP_LENGTH_TYPE)strlen ( srcfilename ),

        &aftp_rc );

if ( aftp_rc == AFTP_RC_OK ) {

     printf ( "File successfully transfered.\n" );

}

This is an example of how to show error reporting.

AFTP_LENGTH_TYPE return_length;

char error_string[ AFTP_MESSAGE_SIZE ];

printf ( "Error %lu transfering the file.\n", aftp_rc );

Specify a detail level according to how much information you want returned. In this case, return code information is requested.

aftp_format_error (

       connection_id,

       (AFTP_DETAIL_LEVEL_TYPE)AFTP_DETAIL_RC,

       (unsigned char AFTP_PTR)error_string,

       (AFTP_LENGTH_TYPE)( sizeof ( error_string )-1 ),

       &return_length,

       &aftp_rc );

Add a null terminator.

    error_string[ return_length ] = '\0';

    printf ( "%s", error_string );

}

Close a connection with AFTPD server.

aftp_close ( connection_id, &aftp_rc );

if ( aftp_rc != AFTP_RC_OK ) {

     printf ( "Error closing the connection.\n" );

     exit ( -1 );

}

Destroy the connection id.

aftp_destroy ( connection_id, &aftp_rc );

if (aftp_rc != AFTP_RC_OK) {

     printf ( "Error destroying the connection id.\n" );

     exit ( -1 );

}

return(0);

}

/* END SAMPLE PROGRAM */


Glossary

This glossary includes terms and definitions from:

The American National Standard Dictionary for Information Systems,

•	ANSI X3.172-1990, copyright 1990 by the American National Standards Institute (ANSI). Copies may be purchased from the American National Standards Institute, 11 West 42nd Street, New York, New York 10036. Definitions are identified by the symbol (A) after the definition.

•	The ANSI/EIA Standard--440-A, Fiber Optic Terminology. Copies may be purchased from the Electronic Industries Association, 2001 Pennsylvania Avenue, N.W., Washington, DC 20006. Definitions are identified by the symbol (E) after the definition.

•	The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions taken from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1.

•	The Network Working Group Request for Comments: 1208.

•	The IBM Dictionary of Computing, New York: McGraw-Hill, 1994.

•	The Object-Oriented Interface Design: IBM Common User Access Guidelines, Carmel, Indiana: Que, 1992.

The following cross-references are used in this glossary:

CONTRAST WITH: This refers to a term that has an opposed or substantively different meaning.

SYNONYM FOR: This indicates that the term has the same meaning as a preferred term, which is defined in its proper place in the glossary.

SYNONYMOUS WITH: This is a backward reference from a defined term to all other terms that have the same meaning.

SEE: This refers the reader to multiple-word terms that have the same last word.

SEE ALSO: This refers the reader to terms that have a related, but not synonymous, meaning.

DEPRECATED TERM FOR: This indicates that the term should not be used. It refers to a preferred term, which is defined in its proper place in the glossary.

A

ACOPY

A transaction program which provides a command line interface to the APPC File Transfer Protocol (AFTP) facility.

ADVANCED PEER-TO-PEER NETWORKING (APPN)

An extension to SNA featuring (a) greater distributed network control that avoids critical hierarchical dependencies, thereby isolating the effects of single points of failure; (b) dynamic exchange of network topology information to foster ease of connection, reconfiguration, and adaptive route selection; (c) dynamic definition of network resources; and (d) automated resource registration and directory lookup. APPN extends the LU 6.2 peer orientation for end-user services to network control and supports multiple LU types, including LU 2, LU 3, and LU 6.2.

ADVANCED PROGRAM-TO-PROGRAM COMMUNICATION (APPC)

(1) The general facility characterizing the LU 6.2 architecture and its various implementations in products. (2) Sometimes used to refer to the LU 6.2 architecture and its product implementations as a whole, or to an LU 6.2 product feature in particular, such as an APPC application program interface.

AFTP

(1) APPC File Transfer Protocol. (2) The client transaction program for the APPC File Transfer Protocol facility. (3) An interactive full-screen environment with a specific set of commands used to manage and transfer files between a client and server computer.

AFTPD

The server transaction program for the APPC File Transfer Protocol facility.

API

(1) Application program interface. (2) Application programming interface.

APING

(1) The APPC Connectivity Tester facility. (2) The client transaction program for the APPC Connectivity Tester facility.

APINGD

The server transaction program for the APPC Connectivity Tester facility.

APPC

Advanced program-to-program communication.

APPLICATION PROGRAMMING INTERFACE (API)

The set of programming language constructs or statements that can be coded in an application program to invoke the specific functions and services provided by an underlying operating system or service program.

APPN

Advanced Peer-to-Peer Networking.

A3270

The server transaction program for the APPC 3270 Terminal Emulator facility.

C

CLIENT

(1) A functional unit that receives shared services from a server. (T) (2) A user.

COMMON PROGRAMMING INTERFACE FOR COMMUNICATIONS (CPI-C)

An evolving application programming interface (API), embracing functions to meet the growing demands from different application environments and to achieve openness as an industry standard for communications programming. CPI-C provides access to interprogram services such as (a) sending and receiving data, (b) synchronizing processing between programs, and (c) notifying a partner of errors in the communication.

CONNECTIVITY

(1) The capability of a system or device to be attached to other systems or devices without modification. (T) (2) The capability to attach a variety of functional units without modifying them.

CONVERSATION

A logical connection between two transaction programs using an LU 6.2 session. Conversations are delimited by brackets to gain exclusive use of a session.

CPI-C

Common Programming Interface for Communications.

CURRENT DIRECTORY

The first directory in which the operating system looks for programs and data files and stores files for output.

D

DATABASE

(1) A collection of data with a given structure for accepting, storing, and providing, on demand, data for multiple users. (T) (2) A collection of interrelated data organized according to a database schema to serve one or more applications. (T) (3) A collection of data fundamental to a system. (A) (4) A collection of data fundamental to an enterprise. (A)

DATA SET MEMBERS

Members of partitioned data sets that are individually named elements of a larger file that can be retrieved by name.

DIRECTORY

(1) A list of files that are stored on a disk or diskette. A directory also contains information about the files such as size and date of last change. (2) A named grouping of files in a file system.

F

FULLY QUALIFIED LU NAME

The two-part network address (network.lu) that uniquely identifies a destination (typically a user) in the network.

L

LOGICAL UNIT (LU)

A type of network accessible unit that enables end users to gain access to network resources and communicate with each other.

LU

Logical unit.

M

MODE NAME

The name used by the initiator of a session to designate the characteristics desired for the session, such as traffic pacing values, message-length limits, sync point and cryptography options, and the class of service within the transport network.

MVS

Multiple Virtual Storage. Implies MVS/370, the MVS/XA product, and the MVS/ESA product.

N

NT OPERATING SYSTEM

Microsoft Windows NT operating system.

P

PACKET

In data communication, a sequence of binary digits, including data and control signals, that is transmitted and switched as a composite whole. The data, control signals, and, possibly, error control information are arranged in a specific format. (I)

PARTITIONED DATA SET (PDS)

A data set in direct access storage that is divided into partitions, called members, each of which can contain a program, part of a program, or data.

PASSWORD

A string of characters that a user, a program, or a computer operator must specify to meet security requirements before gaining access to a system and to the information stored within it.

PATTERN-MATCHING CHARACTER

A special character such as an asterisk (*) or a question mark (?) that can be used to represent one or more characters. Any character or set of characters can replace a pattern-matching character. Synonymous with wildcard character.

PROTOCOL

(1) A set of semantic and syntactic rules that determine the behavior of functional units in achieving communication. (I) (2) In Open Systems Interconnection architecture, a set of semantic and syntactic rules that determine the behavior of entities in the same layer in performing communication functions. (T) (3) In SNA, the meanings of, and the sequencing rules for, requests and responses used for managing the network, transferring data, and synchronizing the states of network components.

R

ROOT DIRECTORY

The first directory on a drive in which all other files and subdirectories exist.

S

SERVER

(1) A functional unit that provides shared services to workstations over a network; for example, a file server, a print server, a mail server. (T) (2) In a network, a data station that provides facilities to other stations; for example, a file server, a print server, a mail server. (A)

SESSION

(1) In network architecture, for the purpose of data communication between functional units, all the activities which take place during the establishment, maintenance, and release of the connection. (T) (2) A logical connection between two network accessible units (NAUs) that can be activated, tailored to provide various protocols, and deactivated, as requested. Each session is uniquely identified in a transmission header (TH) accompanying any transmissions exchanged during the session.

SNA

Systems Network Architecture.

SUBDIRECTORY

A directory contained within another directory in a file system hierarchy.

SYSTEMS NETWORK ARCHITECTURE (SNA)

The description of the logical structure, formats, protocols, and operational sequences for transmitting information units through, and controlling the configuration and operation of, networks. The layered structure of SNA allows the ultimate origins and destinations of information, that is, the end users, to be independent of and unaffected by the specific SNA network services and facilities used for information exchange.

T

TP

Transaction program.

TRANSACTION PROGRAM

A program that processes transactions in an SNA network. There are two kinds of transaction programs: application transaction programs and service transaction programs. See also conversation.

U

USER ID

A string of characters that uniquely identifies a user to a system.

V

VM

Virtual machine.

W

WILDCARD CHARACTER

Synonym for pattern-matching character.