The C subroutine interface of FTP is closely based on the interactive interface and is implemented by the C function YAPFAPI. The calling program transfers the FTP command to YAPFAPI as a character string. As a result, YAPFAPI returns FTP server message(s) and local error information to corresponding buffers.
If the calling program does not want to write the output of a dir or ls command to file but, for example, wishes to interpret it directly, it uses the dirCallBackFct parameter (see below) to transfer the address of a corresponding callback function with the following signature:
void dirCallBackFct(char *buffer, int bufLen);
buffer here is a pointer to a buffer containing part of the output of a dir or ls command. buflen specifies the length of the buffer contents.
If client authentication is used for TLS-secured channels, the calling program can transfer a passphrase for the private key.
When linking the program which calls the FTP subroutine interface, users of the FTP subroutine interface using the standard C/C++ compiler should link the FTPAPI module in from the following library:
SYSLIB.TCP-IP-AP.nnn SKUOML.TCP-IP-AP.nnn | (for /390 servers) (for x86 servers) |
In addition, the external reference to the user-defined exit routine must be resolved (see the “interNet Services Administrator Guide”). If you do not need an exit routine of your own, you can use dummy module EXITFTP from the following library for this purpose:
SYSLNK.TCP-IP-AP.nnn SKMLNK.TCP-IP-AP.nnn | (for /390 servers) (for x86 servers) |
As the FTP subroutine module is produced from C source texts, C runtime libraries (CRTE) must also be linked in.
Function prototype of YAPFAPI
The function prototype of the subroutine call is as follows:
void YAPFAPI(struct YAPFAPI_pl_mdl *param)
param is a pointer to a variable of the type struct YAPFAPI_pl_mdl.
Description of the structure YAPFAPI_pl_mdl
Data type struct YAPFAPI_pl_mdl which is described below is declared in the header file YAPFAPI.H in the library SYSLIB.TCP-IP-AP.nnn.
struct YAPFAPI_pl_mdl {
struct {
int version; /* Interface version */
char *cmd; /* Contains command string */
char *serverMsg; /* Buffer for server messages */
int maxServerMsgLen; /* Length of buffer for server messages */
char *localMsg; /* Buffer for local messages */
int maxLocalMsgLen; /* Length of buffer for local messages */
int combineMessages; /* Write all messages into one buffer */
void (*dirCallBackFct)(char*, int); /* Call back function */
char *passPhrase; /* Password for private key */
int passPhraseLen; /* Length of password for private key */
} in_data;
struct {
int msgNumber; /* Message number of last message from server */
int serverMsgLen; /* Length of messages from server */
int localMsgLen; /* Length of local message */
int rc; /* Summary return code */
} out_data;
}
/* Values for rc */
#define YAPFAPIrcOk 0 /* Ok */
#define YAPFAPIrcVersionError 1 /* Wrong interface version */
#define YAPFAPIrcInitError 2 /* Initialization Error */
#define YAPFAPIrcLocalError 3 /* Local error */
#define YAPFAPIrcFatalLocalError 4 /* Fatal local error */
#define YAPFAPIrcRemoteError 5 /* Remote error */
Description of the structure elements
version
Interface version. This parameter must be assigned the value 1.
cmd
Pointer to the null terminated command string which contains the command in the same syntax as required by the interactive interface (see the section “Overview of commands (FTP client)”).
serverMsg
Pointer to a buffer provided by the calling program to receive the server messages.
maxServerMsgLen
Length of the buffer to which serverMsg points. If the buffer size is not sufficient to accommodate all the messages, the excess messages are either output in fragments or not at all.
localMsg
Pointer to a buffer provided by the calling program to receive local messages.
maxLocalMsgLen
Length of the buffer to which serverMsg points. If the buffer size is not sufficient to accommodate all the messages, the excess messages are either output in fragments or not at all.
combineMessages
If the calling program specifies a value other than 0 for combineMessages, both server messages and local messages are made available in the buffer referenced by localMsg. In this case no separate buffer need be provided for server messages.
dirCallBackFct
Address of a callback function. If no callback function is to be used, NULL must be specified.
passPhrase
Pointer to a buffer which contains the passphrase for the private key.
passPhraseLen
Length of the passphrase.
msgNumber
The number of the last server message is returned in msgNumber as per RFC 959 (FTP).
serverMsgLen
The integer value returned in serverMsgLen shows how many characters have currently been transferred to the buffer specified by serverMsg.
localMsgLen
The integer value returned in localMsgLen shows how many characters have currently been transferred to the buffer specified by localMsg.
rc
The complete return code is returned in rc.
Sample program for the use of the FTP subroutine interface
A sample program is shown below which uses the FTP subroutine interface.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "yapfapi.h"
void printDir(char*, int);
main(int argc, char *argv[])
{
struct YAPFAPI_pl_mdl param;
char line[200];
char serverMsg[2000];
char localMsg[2000];
FILE *fp_in;
fp_in = fopen("(SYSDTA)", "r");
for (;;) {
printf("ftp> ");
if (fgets(line, sizeof line, fp_in) == 0)
break;
param.in_data.version = 1;
param.in_data.cmd = line;
param.in_data.serverMsg = serverMsg;
param.in_data.maxServerMsgLen = sizeof(serverMsg);
param.in_data.localMsg = localMsg;
param.in_data.maxLocalMsgLen = sizeof(localMsg);
param.in_data.combineMessages = 1;
param.in_data.dirCallBackFct = &printDir;
param.in_data.passPhrase = "ABCDEFGH";
param.in_data.passPhraseLen = 8;
YAPFAPI(¶m);
printf("Ret: msgNumber: %d\n", param.out_data.msgNumber);
if (param.out_data.serverMsgLen != 0)
printf("Ret: serverMsgLen: %d\n", param.out_data.serverMsgLen);
printf("Ret: localMsgLen: %d\n", param.out_data.localMsgLen);
if (param.out_data.serverMsgLen != 0) {
serverMsg[param.out_data.serverMsgLen] = '\0';
printf("Ret: serverMsg: \n");
printf("%s", serverMsg);
printf("Ret: serverMsgEnd\n");
}
localMsg[param.out_data.localMsgLen] = '\0';
printf("Ret: localMsg: \n");
printf("%s", localMsg);
printf("Ret: localMsgEnd\n");
printf("Ret: rc: %d\n", param.out_data.rc);
if (param.out_data.rc == YAPFAPIrcInitError)
break;
}
}
void printDir(char* buffer, int bufLen)
{
printf("%.*s", bufLen, buffer);
}