You can use ft_showdir() to determine the attributes of the files in a directory in the remote system. Each call determines as many attribute records as you have specified in the bufsize parameter. If the volume of data in the directory on the remote system is greater, then you have to call ft_showdir() more than once. Please note that you cannot select files within a directory.
Use the function ft_show() to determine the attributes of an individual file/directory.Directory names must not exceed the length specified in the maxrfnsize field of the ft_prop structure (see section “ft_properties - Determine properties of the program interface”).
Syntax
#include <ftapi.h>
long ft_showdir(const struct ft_admission *admis,/* input */
const struct ft_shwpar *par, /* input */
struct ft_fileinfo *buf,
int bufsize, /* input */
struct ft_err *errorinfo,
void *options); /* input */
Parameter
admis
Transfer admission of the remote system (see section “ft_admission” (Specifications concerning the remote system)).
par
Parameters for the request, which you specify with the structure ft_shwpar:
struct ft_shwpar
{
int shwparvers; /* input */
char *fn; /* input */
char *mgmtpasswd; /* input */
char *fud; /* input */
int fudlen; /* input */
enum ft_fncmode fncmode; /* input */
};
The fields of the structure ft_shwpar have the following meanings:
shwparvers
Version of the data structure.
shwparvers must be supplied the value FT_SPARV1, FT_SPARV2 or FT_SPARV3.
fn
Name of the directory for which the attributes are to be determined.
Absolute and relative path names are permissible. Relative path names refer to the login name specified in the admission profile, when the FTAC function is used, otherwise to the HOME directory, see "File transfer".
mgmtpasswd
Password of the directory if it is password-protected.
fud
Address of a data area for the so-called "Further Details" which can indicate a more detailed cause of error if errors occur.
If NULL is specified then no more detailed error cause is output. The fud parameter is only available if shwparvers is set to the value FT_SPARV2 and the options parameter is specified when ft_showdir is called.
fudlen
Length of the data area for fud.
The fudlen parameter is only available if shwparvers is set to the value FT_SPARV2 and the options parameter is specified when ft_showdir is called.
fncmode
Specifies the file-name encoding-mode.
FT_FNCTRANS
Specification of the remote file name and follow-up processing for the remote system in transparent mode (compatible to the previous version; default value after initialization with binary 0).
FT_FNCCHAR
Specification of the remote file name and follow-up processing for the remote system in character mode. They are interpreted according to the character code of the remote system, i.e. for UNIX partners according to the openFT operating parameter option (ftmodo –fnccs) that has been set there. –fnc=c is only permitted for openFT partners as of openFT V12.1B. This functionality is only available if shwparvers is set to the value FT_SPARV3 and the Options parameter is specified when ft_transfer is called.
buf
Area in which the file attributes are written. The area comprises elements with the structure ft_fileinfo:
#define ACC_LEN 65
#define INFO_FN_LEN 257
#define LQ_LEN 81
#define USER_LEN 68
struct ft_fileinfo
{
int ftshowivers; /* input */
char fn[INFO_FN_LEN]; /* output */
enum ft_ftype filetype; /* output */
enum ft_charset charset; /* output */
enum ft_rform recordform; /* output */
long recsize; /* output */
enum ft_available availability; /* output */
int access; /* output */
char accout[ACC_LEN]; /* output */
long size; /* output */
long maxsize; /* output */
char legalqual[LQ_LEN]; /* output */
char cre_user[USER_LEN]; /* output */
long cre_date; /* output */
char mod_user[USER_LEN]; /* output */
long mod_date; /* output */
char rea_user[USER_LEN]; /* output */
long rea_date; /* output */
char atm_user[USER_LEN]; /* output */
long atm_date; /* output */
long long fsize; /* output */
long long fmaxsize; /* output */
};
The fields of the structure ft_fileinfo have the following meanings:
ftshowivers
Version of the data structure.
ftshowivers must be supplied the value FT_SHOWIV1 or FT_SHOWIV2. ftshowivers need only be set in the first passed data structure.
fn
File name or directory name.
filetype
File type:FT_TYPEUNKN
File type unknown.
FT_BIN
Binary file.
FT_DIR
Directory.
FT_TXT
Text file.
charset
Character set (only for text files):
FT_NOSET
Unknown character set.
FT_VISIBLE
The file can contain characters from the ISO646 G0 set.
FT_IA5
The file can contain characters from the ISO646 C0 set and G0 set.
FT_GRAPHIC
The file can contain characters from the ISO646 G0 set or from the ISO8859-1 G0 set and the ISO8859-1 G1 set.
FT_GENERAL
The file can contain characters from the ISO646 C0 set, the ISO646 or ISO8859-1 G0 set and the ISO8859-1 G1 set.
recordform
Record format: FT_NOFORM
Unknown record format.
FT_VARIABLE
Variable record length.
FT_FIXED
Fixed record length.
FT_UNDEF
Undefined record length.
recsize
Maximum record length or 0 if the maximum record length is unknown.
availability
Availability of the file: FT_NOAVAIL
The availability is not defined.
FT_AVAILIMM
The file is available immediately.
FT_AVAILNIMM
The file is not available immediately.
access
Access rights. The right is present if the bit is set. The following bits are defined: FT_ACCR
The file may be read.
FT_ACCI
File units may be added to the file.
FT_ACCP
The file may be overwritten.
FT_ACCX
The file may be extended, i.e. data can be added to the file.
FT_ACCE
File units may be deleted from the file.
FT_ACCA
File attributes may be read.
FT_ACCC
File attributes may be modified.
FT_ACCD
The file may be deleted.
account
Account number used to charge costs in the remote system.
size
Current file size in bytes, or -1 if file size unknown. In systems in which variables of type long have a size of 32 bits, the value for the file size is truncated if it no longer fits in the field. The complete value for the file size can be found in the fsize field.
maxsize
Permissible file size, or -1 if file size unknown. In systems in which variables of type long have a size of 32 bits, the value for the file size is truncated if it no longer fits in the field. The complete value for the file size can be found in the fmaxsize field.
legalqual
Legal qualification.
cre_user
User who created the file.
cre_date
Time at which file was created, or 0 if time unknown.
The time is specified in internal format (seconds since 1.1.1970 00:00:00).
mod_user
User who last modified the file contents.
mod_date
Time at which the file contents were last modified, or 0 if time unknown.
The time is specified in internal format (seconds since 1.1.1970 00:00:00).
rea_user
User who read the file last.
rea_date
Time at which the file was last read, or 0 if time unknown.
The time is specified in internal format (seconds since 1.1.1970 00:00:00).
atm_user
File user who last modified the file attributes.
atm_date
Time at which the file attributes were last modified, or 0 if time unknown.
The time is specified in internal format (seconds since 1.1.1970 00:00:00).
fsize
Current file size in bytes or -1 if the file size is unknown. The fsize parameter is only available if ftshowivers is set to the value FT_SHOWIV2 and the options parameter is specified when ft_showdir is called.
fmaxsize
Current file size in bytes or -1 if the permitted file size is unknown. The fmaxsize parameter is only available if ftshowivers is set to the value FT_SHOWIV2 and the options parameter is specified when ft_showdir is called.
bufsize
Size of buf, i.e. maximum number of elements with the structure ft_fileinfo that will fit in buf.
errorinfo
Area in which detailed information is stored if an error is encountered (see section “ft_err” (Error handling)).
The specification of this parameter is optional. If you do not require any more precise error information then you can specify the value NULL for errorinfo.
options
The specification of the options parameter is optional. If the value NULL is specified then message activity at the program interface is compatible with that of the program interface of openFT < V10.
Alternatively, it is possible to specify the ft_options structure (see section “ft_options” (Version of the program interface)) to activate the openFT message number scheme as of openFT V10 and the extensions to the function.
Return value
n | Number of files found in the remote directory (n >= 0). |
-1 | Error. No information was returned for the directory. |