ft_transfer() sendet eine Datei ins ferne System oder holt eine Datei aus dem fernen System.
Um Dateien synchron zu übertragen, muss der Parameter synchron in der Struktur par den Wert FT_SYNC enthalten.
Um Dateien asynchron zu übertragen, muss der Parameter synchron in der Struktur par den Wert FT_ASYNC enthalten.
Bei asynchronen Dateiübertragungen liefert die Funktion ft_transfer() eine Request-Id zurück, die Sie angeben müssen, wenn Sie sich auf diesen Auftrag beziehen.
Dateinamen dürfen die in der Struktur ft_prop im Feld maxlfnsize bzw. maxrfnsize angegebene Länge nicht überschreiten (siehe Abschnitt „ft_properties - Eigenschaften der Programmschnittstelle ermitteln").
Syntax
#include <ftapi.h>
long ft_transfer(const void *session, /* Eingabe */
const struct ft_admission *admis, /* Eingabe */
const struct ft_transpar *par, /* Eingabe */
struct ft_err *errorinfo,
void *options); /* Eingabe */
Parameter
session
Bei asynchroner Übertragung:
Sitzungsnummer der Sitzung, in der der Übertragungsauftrag ausgeführt werden soll.
Bei synchroner Übertragung:
session muss den Wert NULL haben.
admis
Angaben für das ferne System (siehe Abschnitt „ft_admission" (Angaben zum fernen System)).
par
Angaben für den Auftrag, die Sie mit der Struktur ft_transpar bekanntgeben:
struct ft_transpar
{
int ftparvers; /* Eingabe */
enum ft_direction direction; /* Eingabe */
enum ft_sync synchron; /* Eingabe */
char *locfn; /* Eingabe */
char *remfn; /* Eingabe */
enum ft_filetype filetype; /* Eingabe */
enum ft_writemode writemode; /* Eingabe */
enum ft_compress compress; /* Eingabe */
char *filepasswd; /* Eingabe */
char *locsuccproc; /* Eingabe */
char *locfailproc; /* Eingabe */
char *remsuccproc; /* Eingabe */
char *remfailproc; /* Eingabe */
long maxrecsize; /* Eingabe */ long cantime; /* Eingabe */ long starttime; /* Eingabe */ enum ft_prio priority; /* Eingabe */ enum ft_transpar transparent; /* Eingabe */ enum ft_encrypt encryption; /* Eingabe */ struct ft_transftam *ftamext; /* Eingabe */ char *locccsn; /* Eingabe */ char *remccsn; /* Eingabe */ enum ft_tabexp tabexp; /* Eingabe */ char *fud; /* Eingabe */ int fudlen; /* Eingabe */ enum ft_rform rform; /* Eingabe */ enum ft_tff tff; /* Eingabe */ enum ft_trf trf; /* Eingabe */ enum ft_moddate moddate; /* Eingabe */ };
Hinweis
Für bestimmte Parameter gelten Defaultwerte (s.u.), wenn Sie diese Parameterliste mit den Angaben für den Übertragungsauftrag mit binär 0 initialisieren.
Sie initialisieren die Parameterliste mit binär 0 z.B. mit dem Befehl:memset (transpar, '\0', sizeof(struct ft_transpar));
Die Felder der Struktur ft_transpar haben folgende Bedeutung:
ftparvers
Version der Datenstruktur.
ftparvers muss mit dem Wert FT_TPARV1 oder FT_TPARV2 versorgt werden.
direction
Richtung der Dateiübertragung:
FT_SEND
Datei ins ferne System senden.
FT_RECEIVE
Datei aus dem fernen System holen. Beim Holen einer Datei können Sie keine Wildcards verwenden.
synchron
gibt an, wie die Datei übertragen werden soll:
FT_ASYNC
Asynchrone Übertragung (Defaultwert nach Initialisierung mit binär 0).
FT_SYNC
Synchrone Übertragung.
locfn
Dateiname im lokalen System oder Vor-/Nachverarbeitungskommdo.
Beim lokalen Dateinamen kann jetzt auch ein Vorverarbeitungskommando (beim Senden von Daten) oder ein Nachverarbeitungskommando (beim Empfangen von Daten) angegeben werden.
Absolute und relative Pfadangaben sind erlaubt. Relative Pfadangaben beziehen sich auf das Dateiverzeichnis, in dem das Programm gestartet wird.
remfn
Dateiname im fernen System oder Vor-/Nachverarbeitungskommando.
Beim fernen Dateinamen kann auch ein Vorverarbeitungskommando (beim Empfangen von Daten) oder ein Nachverarbeitungskommando (beim Senden von Daten) angegeben werden.
Absolute und relative Pfadangaben sind erlaubt. Relative Pfadangaben
beziehen sich auf die im Berechtigungsprofil festgelegte Benutzerkennung, wenn die FTAC-Funktion eingesetzt wird, sonst auf das HOME-Verzeichnis, siehe "Dateiübertragung". Daneben kann, wie beim Kommando ncopy, anstelle eines Dateinamens ein Vorverarbeitungskommando mit vorangestelltem Pipe-Zeichen (|) verwendet werden (siehe auch Kommandobeschreibung zu ncopy).
filetype
Dateityp im lokalen System: FT_NOTYPE
keine Festlegung des Dateityps. Es gelten die Standardwerte (siehe Handbuch "openFT (Unix- und Windows-Systeme) - Kommandoschnittstelle", Kommando ft). (Defaultwert nach Initialisierung mit binär 0)
FT_TEXT
Die Datei enthält Text mit variablen Satzlängen. Sätze sind in Windows durch CRLF (X’0D0A’) und in Unix-Systemen durch das Zeichen Zeilenvorschub \n abgeschlossen.
FT_USER
Die Datei enthält vom Benutzer strukturierte Binärdaten mit variabler Satzlänge. Jeder Satz beginnt mit zwei Bytes, die die Längenangabe des Satzes enthalten.
FT_BINARY
Die Datei enthält eine unstrukturierte Folge von Binärdaten.
writemode
gibt an, ob die Zieldatei neu erzeugt, überschrieben oder erweitert werden soll:
FT_NOMODE
keine Festlegung der Schreibregel. Es gelten die Standardwerte (siehe Handbuch "openFT (Unix- und Windows-Systeme) - Kommandoschnittstelle", Kommando ft). (Defaultwert nach Initialisierung mit binär 0)
FT_OVERWR
Eine bereits vorhandene Zieldatei wird überschrieben. War die Zieldatei noch nicht vorhanden, wird sie neu eingerichtet.
FT_EXTEND
Die übertragene Datei wird an das Ende einer bereits vorhandenen Zieldatei angehängt. War die Zieldatei noch nicht vorhanden, wird sie neu eingerichtet.
FT_NEW
Die Zieldatei wird neu erzeugt und beschrieben. Ist die Zieldatei
bereits vorhanden, wird der Auftrag abgelehnt.
compress
Gibt an, ob komprimiert übertragen werden soll: FT_NOCOMPR
Keine Komprimierung (Defaultwert nach Initialisierung mit binär 0).
FT_COMPRESS
Mehrere gleiche, aufeinanderfolgende Zeichen werden in komprimierter Form übertragen (Byte-Komprimierung).
FT_COMPRESSZIP
Zip-Komprimierung. Bei Kopplung zu Partnern, die diese Komprimierung nicht unterstützen wird automatisch auf Byte-Komprimierung oder keine Komprimierung umgeschaltet. Die Zip-Kompression steht nur zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2 gesetzt wird und beim Aufruf von ft_transfer der Parameter options angegeben ist.
filepasswd
Kennwort der Datei im fernen System, falls sie mit einem Kennwort geschützt ist.
locsuccproc
Kommando, das im lokalen System im Anschluss an eine erfolgreiche asynchrone Dateiübertragung ausgeführt wird.
Bei synchronen Übertragungsaufträgen darf locsuccproc nicht angegeben werden.
Innerhalb des Kommandos bzw. der Kommandofolge für die Folgeverarbeitung können Variablen angegeben werden. Weitere Informationen siehe Abschnitt „Kommandos für Folgeverarbeitung"".
locfailproc
Kommando, das im lokalen System ausgeführt wird, wenn eine asynchrone Dateiübertragung durch einen Fehler abgebrochen wurde.
Bei synchronen Übertragungsaufträgen darf locfailproc nicht angegeben werden.
Innerhalb des Kommandos bzw. der Kommandofolge für die Folgeverarbeitung können Variablen angegeben werden.Weitere Informationen siehe Abschnitt „Kommandos für Folgeverarbeitung"".
remsuccproc
Kommando, das im fernen System im Anschluss an eine erfolgreiche Dateiübertragung ausgeführt wird.
Einige Partnersysteme (z.B. openFT (BS2000)) unterstützen sogar Folgen aus mehreren Kommandos. Im Anschluss an eine erfolgreiche Übertragung werden diese Kommandos im fernen System unter dem angegebenen login ausgeführt.
Innerhalb des Kommandos bzw. der Kommandofolge für die Folgeverarbeitung können Variablen angegeben werden. Weitere Informationen siehe Abschnitt „Kommandos für Folgeverarbeitung"".
remfailproc
Kommando, das im fernen System ausgeführt wird, wenn eine Dateiübertragung durch einen Fehler abgebrochen wurde.
Einige Partnersysteme (z.B. openFT (BS2000)) unterstützen sogar Folgen aus mehreren Kommandos. Diese Kommandos werden im fernen System unter dem angegebenen login ausgeführt, wenn eine bereits begonnene Dateiübertragung durch einen Fehler abgebrochen wurde.
Innerhalb des Kommandos bzw. der Kommandofolge für die Folgeverarbeitung können Variablen angegeben werden. Weitere Informationen siehe unten bei "Kommandos für Folgeverarbeitung".
Kommandos für Folgeverarbeitung
Die Angaben für die lokale Folgeverarbeitung, also für locsuccproc und locfailproc zusammen, dürfen nicht mehr als 1000 Zeichen betragen.
Die Angaben für die ferne Folgeverarbeitung, also für remsuccproc und remfailproc zusammen, dürfen nicht mehr als 1000 Zeichen betragen.
Variable werden bei Start der Folgeverarbeitung im lokalen bzw. im fernen System durch Werte ersetzt, die sich aus der Funktion ft_transfer() ergeben.
Als Variablen stehen Ihnen %FILENAME für Dateiname, %PARTNER für den Partnernamen, %RESULT für das Ergebnis des Auftrags und %RID für die Request-Id zur Verfügung.
%RID ist nur für lokale Folgeverarbeitung erlaubt.
Nach dem Start der Folgeverarbeitung werden die Variablen im jeweiligen System ersetzt. Anschließend werden die Kommandos der Folgeverarbeitung ausgeführt.
Folgende Variablenersetzungen sind möglich:%FILENAME
Durch den Dateinamen, wie er im Auftrag für das entsprechende System angegeben wurde%PARTNER
Bei lokaler Folgeverarbeitung durch den beim Aufruf angegebenen Partnernamen. Bei Folgeverarbeitung im fernen System wird %PARTNER durch den Namen des Auftraggeber-Systems ersetzt, d.h. durch den Namen, mit dem es im Partnersystem bekannt ist.%RESULT
Durch die Meldungsnummer des Auftrags bezogen auf das jeweilige System. So erhält %RESULT z.B. bei erfolgreicher Ausführung eines Auftrags die Meldungsnummer 0 (Wird für options der WertNULLangegeben, dann ist das Meldungsverhalten der Programmschnittstelle kompatibel zur Programmschnittstelle von openFT < V10).%RID
Durch die Request-Id des Auftrags im lokalen System.
Ist das Partnersystem ein openFT (BS2000), dann können Sie auch die Variablen %ELEMNAME, %ELEMVERS und %ELEMTYP verwenden.
In Windows stehen bei der Folgeverarbeitung im lokalen System nur die System-Umgebungsvariablen zur Verfügung.
Bei der Folgeverarbeitung im lokalen Unix-System und bei Folgeverarbeitung in einem fernen Unix-System wird nicht die in der Datei .profile abgelegte Kommandofolge durchlaufen. Ihnen stehen nur die Standardwerte der Shell-Variablen HOME, LOGNAME, PATH und USER zur Verfügung sowie die von root gesetzten Werte der Shell-Variablen LANG und TZ.
Denken Sie daran, bei der Angabe von BS2000-Kommandos am Anfang des Kommandos den Schrägstrich (/) mit anzugeben.
Bei Aufträgen mit FTAM- und FTP-Partnern steht nur die Funktion "lokale Folgeverarbeitung" zur Verfügung. Wird im fernen System die FTAC-Funktion eingesetzt, dann kann diese Einschränkung umgangen werden. In dem Fall kann im fernen System ein Berechtigungsprofil erzeugt werden, in dem eine Folgeverarbeitung definiert ist.
maxrecsize
maximal zulässige Satzlänge bei Dateien vom Typ "Textdatei" und "strukturierte Binärdatei". Damit können auch Sätze übertragen und abgespeichert werden, die größer als der Standardwert sind. Sie müssen jedoch berücksichtigen, dass nicht alle Satzlängen in jedem beliebigen Partnersystem bearbeitet werden können.
Der Maximalwert darf die in der Struktur ft_prop im Feld maxrecord angegebene Länge nicht überschreiten (siehe Abschnitt „ft_properties - Eigenschaften der Programmschnittstelle ermitteln").
Wenn Sie den Dateityp "binär" gewählt haben, ist maxrecsize der Wert für alle Sätze der Sendedatei.
Bei FTAM-Partnern wird die Angabe zur maximalen Satzlänge nur wirksam, wenn für filetype der Dateityp explizit mit FT_TEXT, FT_USER oder FT_BINARY angegeben wird.
cantime
Zeitpunkt, zu dem ein Übertragungsauftrag abgebrochen werden soll. Dieser Zeitpunkt muss im internen Zeitformat (Sekunden seit dem 1.1.1970 00:00:00) angegeben werden.
Der Wert 0 bedeutet, dass kein zeitgesteuerter Abbruch erfolgt.
Bei synchronen Aufträgen wird cantime ignoriert.
starttime
Zeitpunkt, zu dem ein Übertragungsauftrag frühestens gestartet werden soll. Dieser Zeitpunkt muss im internen Zeitformat (Sekunden seit dem 1.1.1970 00:00:00) angegeben werden.
Der Wert 0 bedeutet, dass die Übertragung so bald wie möglich gestartet wird.
Bei synchronen Aufträgen wird starttime ignoriert.
priority
Gibt die Priorität des Auftrags an:
FT_PRIONORM
normale Priorität (Defaultwert nach Initialisierung mit binär 0)
FT_PRIOLOW
niedrige Priorität (wird bei synchronen Aufträgen ignoriert)
transparent
gibt an, ob die Dateiübertragung transparent sein soll:
FT_NOTRANSPAR
normale Übertragung (Defaultwert nach Initialisierung mit binär 0).
FT_TRANSPARENT
transparente Übertragung.
encryption
Gibt an, ob die Benutzerdaten verschlüsselt werden sollen bzw. ob eine Datenintegritätsprüfung durchgeführt werden soll:
FT_NOENCRYPT
Benutzerdaten werden nicht verschlüsselt und eine Datenintegritätsprüfung wird nicht durchgeführt (Defaultwert nach Initialisierung mit binär 0).
FT_ENCRYPT
Benutzerdaten werden verschlüsselt und die Datenintegrität wird automatisch geprüft.
Dazu muss openFT-CR installiert sein.
FT_ONLYDICHECK
Die Datenintegritätsprüfung des übertragenen Dateiinhalts wird durchgeführt. Die Datenintegritätsprüfung steht nur zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2 gesetzt wird und beim Aufruf von ft_transfer der Parameter options angegeben ist.
ftamext
FTAM-spezifische Parameter, die Sie mit der Struktur ft_transftam bekanntgeben (siehe auch bei den Kommandos ft und ncopy, Optionen -av, -ac, -am, -lq und -cp):
struct ft_transftam
{
enum ft_available available; /* Eingabe */
char *account; /* Eingabe */
int accessmode; /* Eingabe */
char *legalq; /* Eingabe */
char *crpasswd; /* Eingabe */
};
Die Felder der Struktur ft_transftam haben folgende Bedeutung:
available
legt die Verfügbarkeit der Zieldatei fest:
FT_NOAVAIL
keine Festlegung der Verfügbarkeit (Defaultwert nach Initialisierung mit binär 0).
FT_AVAILIMM
Die Zieldatei erhält das Attribut "sofort verfügbar".
FT_AVAILNIMM
Die Zieldatei erhält das Attribut "nicht sofort verfügbar".
account
Abrechnungskonto beim FTAM-Partner
accessmode
Legt die Zugriffsrechte der Zieldatei fest. Die Zugriffsrechte entstehen durch logisches Odern folgender Einzelrechte:
FT_ACCR
Die Datei darf gelesen werden.
FT_ACCI
Dateneinheiten dürfen in die Datei eingefügt werden.
FT_ACCP
Die Datei darf überschrieben werden.
FT_ACCX
Die Datei darf erweitert werden, d.h. Daten können an die Datei angefügt werden.
FT_ACCE
Dateneinheiten dürfen aus der Datei gelöscht werden.
FT_ACCA
Dateiattribute dürfen gelesen werden.
FT_ACCC
Dateiattribute dürfen geändert werden.
FT_ACCD
Die Datei darf gelöscht werden.
legalq
Legt die rechtliche Bestimmung (Copyright) für die Zieldatei fest.
crpasswd
Kennwort, das Sie im fernen System benötigen, um eine Datei zu erzeugen.
locccsn
Gibt den Namen der Codierung an (CCS-Name), mit der die lokale Datei gelesen oder geschrieben wird. CCS-Name muss im lokalen System bekannt sein.
Wird keine Codierung angegeben, wird der bei openFT per Betriebsparameter eingestellte Standardwert für die Codierung verwendet.
Die Unterstützung der "Coded Character Sets" (CCS) steht nur dann zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2 gesetzt wird und beim Aufruf von ft_transfer der Parameter options angegeben ist.
remccsn
Gibt den Namen der Codierung an (CCS-Name), mit der die ferne Datei gelesen oder geschrieben wird. CCS-Name muss im fernen System bekannt sein. Wird keine Codierung angegeben, wird der durch XHCS (BS2000-Systeme) bzw. per openFT-Betriebsparameter (andere Plattformen) eingestellte Zeichensatz für die Codierung verwendet.
Die Unterstützung der "Coded Character Sets" (CCS) wird nur für das openFT-Protokoll und für Partner mit openFT ab V10.0 unterstützt und steht nur dann zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2 gesetzt wird und beim Aufruf von ft_transfer der Parameter options angegeben ist.
tabexp
Gibt an, ob für einen Outbound-Sendeauftrag die Tabulator-Expansion und die Umwandlung leerer Zeilen in Zeilen mit einem Zeichen für nicht-FTAM-Partner durchgeführt werden soll. Die Tabulator-Expansion steht nur zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2 gesetzt wird und beim Aufruf von ft_transfer der Parameter options angegeben ist.
FT_TABAUTO
Tabulator-Expansion und Umwandlung der Leerzeilen sind eingeschaltet, wenn eine Datei zu einem BS2000-, OS/390- oder z/OS-System gesendet wird (Standardwert nach Initialisierung mit binär 0).
FT_TABON
Tabulator-Expansion und Umwandlung der Leerzeilen sind eingeschaltet.
FT_TABOFF
Tabulator-Expansion und Umwandlung der Leerzeilen sind ausgeschaltet.
fud
Adresse eines Datenbereichs für die sogenannten "Further Details", die im Fehlerfall eine genauere Fehlerursache angeben können.
Bei Angabe von NULL wird keine weiterführende Fehlerursache ausgegeben. Der Parameter fud steht nur dann zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2 gesetzt wird und beim Aufruf von ft_transfer der Parameter options angegeben ist.
fudlen
Länge des Datenbereichs von fud.
Der Parameter fudlen steht nur dann zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2 gesetzt wird und beim Aufruf von ft_transfer der Parameter options angegeben ist.
rform
gibt das Satzformat der zu übertragenden Datei an. Der Parameter rform
steht nur dann zur Verfügung, wenn ftparvers auf den Wert FT_TPARV2
gesetzt wird und beim Aufruf von ft_transfer der Parameter options
angegeben ist.
FT_NOFORM
Das Satzformat der zu übertragenden Datei ist unbekannt (Standardwert nach Initialisierung mit binär 0).
FT_VARIABLE
Die zu übertragende Datei enthält Sätze mit variabler Satzlänge.
FT_FIXED
Die zu übertragende Datei enthält Sätze mit einheitlich fester Satzlänge.
FT_UNDEF
Die zu übertragende Datei enthält Sätze mit undefinierter Satzlänge.
tff
Gibt das Format der Zieldatei an:
FT_NOTFF
Format wie die Sendedatei, siehe Feld trf (Standardwert nach Initialisierung mit binär 0).
FT_TFFBLOCK
Die Zieldatei soll block-strukturiert gespeichert werden. Damit kann z.B. eine Datei in das BS2000 übertragen und dort als PAM-Datei abgespeichert werden. Wenn Sie FT_TFFBLOCK angeben, müssen müssen Sie auch file type =FT_BINARY angeben.
FT_TFFSEQU
Die Zieldatei soll als sequentielle Datei gespeichert werden, und das Satzformat soll erhalten bleiben. Damit kann z.B. eine ISAM-Datei oder PAM-Datei aus dem BS2000 geholt werden. Siehe auch trf =FT_TRFUNDEF.
trf
Gibt das Satzformat der Zieldatei an:
FT_NOTRF
Format wie die Sendedatei, siehe Feld tff (Standardwert nach Initialisierung mit binär 0).
FT_TRFUNDEF
Gibt an, dass die Datei als sequentielle Datei übertragen wird und dass das Satzformat der Zieldatei undefiniert sein soll. D.h. die Satzstruktur der Sendedatei geht verloren. Bei der Übertragung in ein BS2000- oder z/OS-System wird pro Übertragungseinheit ein Block geschrieben.
Darf nicht gleichzeitig mit tff =FT_TFFBLOCK angegeben werden!
moddate
Gibt an wie das Änderungsdatum der Zieldatei behandelt werden soll.
Diese Funktion ist nur sinnvoll für Aufträge an BS2000-Partner mit OSD ab V8.0 über das openFT-Protokoll.
FT_MDSRC
Es gilt das Verhalten wie in openFT bis V11.0: Auf Unix- und Windows-Systemen und POSIX (BS2000) wird das Änderungsdatum der Sendedatei übernommen. Auf BS2000 mit DMS wird der aktuelle Zeitpunkt als Änderungsdatum genommen (Standardwert nach Initialisierung mit binär 0).
FT_MDFAIL
Das Änderungsdatum der Sendedatei wird auf die Zieldatei übernommen, wenn das Zielsystem diese Übernahme unterstützt.
Falls das Zielsystem diese Funktion nicht unterstützt, wird der Auftrag abgelehnt.
Darf nicht gleichzeitig mit ft_writemode = FT_EXTEND angegeben werden!
errorinfo
Bereich, in dem genauere Informationen hinterlegt sind, wenn ein Fehler aufgetreten ist (siehe Abschnitt „ft_err" (Fehlerbehandlung)).
Die Angabe des Parameters ist optional. Wenn Sie keine genaueren Fehlerinformationen benötigen, können Sie für errorinfo den Wert NULL angeben.
options
Die Angabe des Parameters options ist optional. Wird der Wert NULL angegeben, dann ist das Meldungsverhalten der Programmschnittstelle kompatibel zur Programmschnittstelle von openFT < V10.
Alternativ können durch die Angabe der Struktur ft_options (siehe Abschnitt „ft_options" (Version der Programmschnittstelle)) das openFT-Meldungsnummernschema ab openFT V10 und die Funktionserweiterungen aktiviert werden.
Rückgabewert
n | Bei erfolgreichen asynchronen Aufträgen: Request-Id (n |
1 | Bei erfolgreichen synchronen Aufträgen. |
0 | Fehler. Die Dateiübertragung wurde nicht angestoßen. |