Janus C-API

Einführung

Die folgende Aufstellung ist ein Auszug aus der C-Header-Datei, die die notwendigen Definitionen für den Einsatz der Janus/TCP-Transport-Protokolle in eigenen Anwendungen enthält.

Die Bibliotheken werden im Quelltext geliefert und sollten sich auf den meisten Plattformen, die TCP/IP-Sockets unterstützen, einsetzen lassen.

Konstanten

Allgemeine Konstanten

#define TRUE                  1
#define FALSE                 0
#define OK                    0
#define NOT_OK                -1
#define TCP_TEXT_SIZE         512
#define TCP_ERROR_TEXT_SIZE   ( TCP_TEXT_SIZE + 32 )
#define TCP_IO_BUFFER_SIZE    32000
#define TCP_NUMBER_SIZE       5
#define TCP_DESTINATION_SIZE  36
#define TCP_HEADER_SIZE       sizeof( TCP_MESSAGE_HEADER )
#define TCP_ACK_SIZE          sizeof( TCP_ACK_MESSAGE )
#define TCP_ERROR_SIZE        sizeof( TCP_ERROR_MESSAGE )
#define TCP_INIT_SIZE         sizeof( TCP_INIT_MESSAGE )
#define TCP_ACCEPT_SIZE       sizeof( TCP_ACCEPT_MESSAGE )
#define TCP_DATA_HEADER_SIZE  ( TCP_HEADER_SIZE + TCP_DESTINATION_SIZE \
                              + TCP_NUMBER_SIZE )
#define TCP_DATA_SIZE         ( TCP_IO_BUFFER_SIZE - TCP_DATA_HEADER_SIZE )
#define TCP_REPLY_HEADER_SIZE TCP_DATA_HEADER_SIZE
#define TCP_REPLY_SIZE        TCP_DATA_SIZE
#define TCP_TRANSACTION_SIZE  sizeof( TCP_TRANSACTION_MESSAGE )

#define TCP_PORT        2000

Fehlertypen

typedef enum _error_type {
    ET_NO_ERROR = 0,
    ET_CPIC,
    ET_APPLICATION,
    ET_SAP_HOST,
    ET_RSC,
    ET_TCPIP,
    ET_RFC
} ERROR_TYPE;

Applikations-Fehler

typedef enum _error_code {
    ERR_OK                   = 0,
    ERR_RECORD_TOO_BIG       = 1,
    ERR_BAD_PARAMETER        = 2,

    ERR_CANNOT_SEND          = 10,
    ERR_CANNOT_DISCONNECT    = 11,
    ERR_DISCONNECTED         = 12,
    ERR_PROTOCOL             = 13,
    ERR_MEMORY               = 14,
    ERR_CONFIRM              = 15,
    ERR_SAP_TABLE            = 16,

    ERR_SAP_DOWN             = 100,
    ERR_TCP_DOWN             = 101,

    ERR_REMOTE               = 200,
    ERR_NO_REMOTE_CONNECTION = 201,

    ERR_FATAL                = 10000,
    ERR_INIFILE              = 10001,
    ERR_65535                = 65535
} ERROR_CODE;

Transaktionstypen

typedef enum _transaction_type {
    TT_NONE        = 'N',
    TT_BEGIN       = 'B',
    TT_COMMIT      = 'E',
    TT_ROLLBACK    = 'R',
    TT_SINGLE      = 'S',
    TT_AUTOCOMMIT  = 'A',
    /*
     *  Nur intern
     */
    TT_IN_PROGRESS = 1
} TRANSACTION_TYPE;

Nachrichtentypen

typedef enum _tcpip_message_type {
    TCP_MT_ACK            = 0,
    TCP_MT_ERROR          = 1,
    TCP_MT_DATA           = 2,
    TCP_MT_REPLY          = 3,
    TCP_MT_TRANSACTION    = 4,
    TCP_MT_INITIALIZE     = 5,
    TCP_MT_ACCEPT         = 6,
    TCP_MT_UNKNOWN        = -1
} TCP_MESSAGE_TYPE;

Anfang

Datenstrukturen

TCP_HOST-Datenstruktur zum Zugriff auf die Kommunikationsroutinen

typedef struct _tcpip_host {
    int connected;                         /* TRUE, wenn Verbindung besteht */
    int option;                            /* Optionen, z. B. Kompression */
    int socket_recv;                       /* TCP/IP-Socket fuer Recieve */
    int socket_send;                       /* TCP/IP-Socket fuer Send */
    unsigned bytes_written;                /* Gesamt-Statistik */
    unsigned bytes_received;               /* dito */
    ERROR_CODE error_code;                 /* Nummer des letzten Fehlers */
    ERROR_TYPE error_type;                 /* Fehler-Art */
    char error_text[ TCP_ERROR_TEXT_SIZE ];/* Text des letzten Fehlers */
    unsigned error_no;                     /* Guardian-Fehler */
    unsigned subsystem;                    /* Subsystem */
    unsigned subsystem_error;              /* Subsystem-Fehler */
    unsigned extended_error;               /* Erweiterter Fehler */
    unsigned error_class;                  /* Fehlerklasse */
    TRANSACTION_TYPE transaction_type;     /* Transaktionsmodus */
    int success_lo, success_hi;            /* Fuer Auto-Transaktionen */
    TCP_MESSAGE_TYPE message_type;         /* Antwort-Datentyp */
    unsigned user_len;                     /* Laenge der Nutzdaten */
    char *user_data;                       /* Begin der Nutzdaten */
    char *destination;                     /* Zeiger auf Daten-Ziel */
    unsigned io_len;                       /* Gesamt-Pufferlaenge */
    char io_buffer[ TCP_IO_BUFFER_SIZE ];  /* Transferpuffer */
    char diff_buffer[ TCP_IO_BUFFER_SIZE ];/* Vergleichspuffer */
} TCP_HOST;

Message-Kopf

typedef struct _tcpip_header {
    char request_id[ 4 ];
    char size[ 5 ];
    char option;
} TCP_MESSAGE_HEADER;

Positive Quittung mit optionalem Text

typedef struct _tcp_ack_message {
    TCP_MESSAGE_HEADER header;
    char error_no[ TCP_NUMBER_SIZE ];
    char text[ TCP_TEXT_SIZE ];
    char reserved[ 8 - TCP_NUMBER_SIZE ];
} TCP_ACK_MESSAGE;

Negative Quittung mit Fehler-Nummer und Text

typedef struct _tcp_error_message {
    TCP_MESSAGE_HEADER header;
    char error_no[ TCP_NUMBER_SIZE ];
    char text[ TCP_TEXT_SIZE ];
    char reserved[ 8 - TCP_NUMBER_SIZE ];
} TCP_ERROR_MESSAGE;

Spezielle Antwort bei Remote-Fehlern

typedef struct _remote_error_reply {
    char error_no[ TCP_NUMBER_SIZE ];
    char subsystem[ TCP_NUMBER_SIZE ];
    char subsystem_error[ TCP_NUMBER_SIZE ];
    char extended_error[ TCP_NUMBER_SIZE ];
    char error_class[ TCP_NUMBER_SIZE ];
    char text[ TCP_TEXT_SIZE - 5 * TCP_NUMBER_SIZE ];
} REMOTE_ERROR_REPLY;

Reply mit Daten (positive Quittung auf DATA)

typedef struct _tcp_reply_message {
    TCP_MESSAGE_HEADER header;
    char transaction_in_progress;
    char reserved[ TCP_DESTINATION_SIZE - 1 ];
    char reply_len[ TCP_NUMBER_SIZE ];
    char reply[ TCP_REPLY_SIZE ];
} TCP_REPLY_MESSAGE;

Daten-Message

typedef struct _tcp_data_message {
    TCP_MESSAGE_HEADER header;
    char destination[ TCP_DESTINATION_SIZE ];
    char data_len[ TCP_NUMBER_SIZE ];
    char data[ TCP_DATA_SIZE ];
} TCP_DATA_MESSAGE;

Aufsplittung der Destination bei UMS-Nachrichten

typedef struct _tcp_ums_destination {
    char terminal[ 10 ];
    char alias[ TCP_DESTINATION_SIZE - TCP_NUMBER_SIZE - 10 ];
    char reply_len[ TCP_NUMBER_SIZE ];
} TCP_UMS_DESTINATION;

Transaktions-Message

typedef struct _tcp_transaktion_message {
    TCP_MESSAGE_HEADER header;
    char code;
    char reserved;
    char success_lo[ TCP_NUMBER_SIZE ];
    char success_hi[ TCP_NUMBER_SIZE ];
} TCP_TRANSACTION_MESSAGE;

Initialisierungs-Message

typedef struct _tcp_init_message {
    TCP_MESSAGE_HEADER header;
    char init_data[ TCP_TEXT_SIZE ];
} TCP_INIT_MESSAGE;

Accept-Message (für umgekehrten Verbindungsaufbau)

typedef struct _tcp_accept_message {
    TCP_MESSAGE_HEADER header;
    char address[ 3 + 1 + 3 + 1 + 3 + 1 + 3 ]; /* IP-Adresse in Text-Form */
    char port[ TCP_NUMBER_SIZE ];              /* IP-Port */
} TCP_ACCEPT_MESSAGE;

Anfang

Funktionen

Auswertung eines Applikationsfehlers

void TCP_ApplicationError( TCP_HOST *host, int err, char *caller );

Verbindungsauf- und Abbau zum Host

TCP_HOST *TCP_Connect( char *host_name, int port, char *initdata );

TCP_HOST *TCP_Accept( int argc, char **argv );

TCP_HOST *TCP_AcceptNew( TCP_HOST *host, int port );

int TCP_Disconnect( TCP_HOST *host );

Datentransfer zum TCP-Host

int TCP_Send( TCP_HOST *host, void *buff, unsigned len );

int TCP_SendAck( TCP_HOST *host, char *text );

int TCP_SendNak( TCP_HOST *host, int err, char *text );

Data-Message schicken und Reply abholen

int TCP_SendData( TCP_HOST *host,
                  char *destination,
                  void *buffer,
                  int len,
                  void *reply,
                  int reply_len );

Transaktionssteuerung

int TCP_Transaction( TCP_HOST *host, TRANSACTION_TYPE code,
                     int success_lo, int success_hi );

REPLY-Message senden (aus host->io_buffer )

int TCP_SendReply( TCP_HOST *host,
                   unsigned int reply_len,
                   char *mess );

Datentransfer vom Host

int TCP_Recv( TCP_HOST *host, void *buff, unsigned maxlen );

Puffer abschicken und Antwort lesen

int TCP_SendRecv( TCP_HOST *host );

Daten vom Host empfangen und Format prüfen

int TCP_RecvData( TCP_HOST *host );

Messagetyp überprüfen

TCP_MESSAGE_TYPE TCP_MessageType( void *buff );

Anfang