XJGATE APIs Guide

XJGATE is a set of APIs that allow a program to connect XCICS over its native terminal protocol, in order to activate transactions and to exchange data with them.

XJGATE APIs are available both for the following programming languages:

The use of the XJGATE APIs is discouraged and maintained only for backward compatibility reasons. Programmers that want to communicate with programs running under XCICS/TS should consider the opportunity to use other communication protocols like SNA ISC, TCP/IP sockets or web services.

The gateway transaction

In order to provide an easier gatewaying interface a gateway program has been provided: XJGT.

To activate XJGT, XCICS must be conigured with the following entries.

define program name=XJGT, language=java, path=com.hite.xjgate.XJGateServer;
define transaction name=XJGT, program=XJGT, twa=512, protection=64;

C language APIs

Include files

In order to use XJGATE APIs the following files must be include in the C source:

The main source must define the symbol NOEXTERN

I.e.

#define NOEXTERN
 
#include "xascebc.h"
#include "socklib.h"
#include "xjgate.h"

Functions

xjgate_connect

prototype

struct Connection *xjgate_connect(char *hostname, int port,char *termname,char *cbldbg,char *asmdbg,int *rc);

description

Connects the application.

return value

Returns a structure identifyng the connection. If failed NULL is returned and "rc" contains the error code.

Example

struct Connection *conn;
conn=xjgate_connect(hostname,port,termname,NULL,NULL,&rc);
if (conn==NULL) {
  fprintf(stderr,"cannot connect (%d):", rc);
  exit(1);
}

xjgate_attach

prototype

int xjgate_attach(struct Connection *c) ;

description

reconnects XCICS engine. Must be issued before starting the data exchange.

return value

Example

rc=xjgate_attach(conn);

xjgate_detach

prototype

int xjgate_detach(struct Connection *c) ;

description

disconnects XCICS engine. Must be issued at the end of the data exchange.

return value

xjgate_send

prototype

int xjgate_send(struct Connection *c, unsigned char *data, int len);

description

Send the specified data to XCICS for the specified len.

return value

xjgate_sendData

prototype

int xjgate_sendData(struct Connection *c, unsigned char *data, int len);

description

Send the specified data to XCICS for the specified len. Data are prefixed by 3 bytes for SNA communication.

return value

xjgate_receive

prototype

int xjgate_receive(struct Connection *c, unsigned char *data, int len);

description

Receives data from XCICS in the specified buffer.

return value

xjgate_checkProtocol

prototype

int xjgate_checkProtocol(unsigned char* buffer, int len);

description

describes the dialogue status.

return value

current dialog status

xjgate_close

prototype

void xjgate_close(struct Connection *c);

description

closes the XCICS connection.

xjgate_activate

prototype

void xjgate_activate(struct Connection *c, char *transid);

description

Activates the specified transaction.

Example

xjgate_activate(conn, "SRV1");

Compiling & Linking

Programs compiled with XJGATE must use the following options:

-I $XFRAMEHOME/include -I $XFRAMEHOME/xsdf/cpy

and linked with:

-L $XFRAMEHOME/lib -lxsocket.a

cc -I $XFRAMEHOME/include -I $XFRAMEHOME/xsdf/cpy -L $XFRAMEHOME/lib -lxsocket.a -o pgm1 pgm1.c

An example

/** Connects XCICS */
struct Connection *conn;
conn=xjgate_connect("hpux01.ht.net",4000,"L001",NULL,NULL,&rc);
if (conn==NULL) {
  fprintf(stderr,"cannot connect (%d):", rc);
  exit(1);
}
 
/**
* connected!!
* initialize dialogue session
*/
rc=xjgate_attach(conn);
if (rc<0) { exit(-1); }
 
/**
* starting the transid XJGT
*/
rc=xjgate_activate(conn, "XJGT");
if(rc<0) { exit(-1); }
 
/**
* data reception loop
*/
while (receive) {
     /** receiving data ... */
     rc=xjgate_receive(conn, buffer, 10000);
     if(rc<0) { return rc; }
      /* checking the protocolo command */
     proto=xjgate_checkProtocol(buffer, rc);
     switch (proto) {
     case XJGATE_DETACH_REQUEST:
          /**
           * XCICS terminated transaction and
           * asks me to detach
           */
          xjgate_detach(conn);
          receive=FALSE;
          break;
     case XJGATE_RECV_REQUEST:
          /** XCICS is ready to receive */
          receive=FALSE;
          break;
     case XJGATE_RECV_BUFFER:
     case XJGATE_TERMINAL_SETUP:
          /**
           * XCICS is asking for a RECEIVE BUFFER or a REMOTE  TERMINAL SETUP
           * cannot handle it
           */
           break;
     default:
          /** 3270 data arriving... */
          printf("received %d bytes\n",rc);
          break;
     }
}
strcpy(buffer,"DATA FOR TRANSACTION");
if (UNPREFIXEDDATA) {
  xjgate_sendData(conn, ebcdic, strlen(buffer);
} else {
  int l=strlen(buffer);
  buffer[0]=0x1d;
  buffer[1]=0x40;
  buffer[2]=0x40;
  memcpy(buffer+3, ebcdic, l);
  xjgate_send(conn, ebcdic, strlen(buffer);
}
xjgate_close(conn);

Java APIs

XJGATE Java APIs may be found in the XJE Java API tree.