Sun Adapter for CICS API

com.stc.eways.cics
Interface CicsClient

All Known Implementing Classes:
CicsClientAdapter, CicsClientExtImpl, CicsClientImpl, CTGCicsClientImpl

public interface CicsClient

The CicsClient class represents an OTD through which a collaboration can invoke transaction programs on a CICS server; nodes and methods are exposed so that collaboration can conveniently prepare a request to a CICS program and invoke the program and get result from the program; in the current implementation, there are two underlying transport mechanism can be used to achieve the remote invoking of CICS programs: (1) CTG - IBM's CICS Transaction Gateway (2) SBYND CICS Listener - SeeBeyond CICS Listener - a light weighted propritary protocol based on TCP/IP; note that, the configuration parameters can be roughly categorized into : CTG specific; SBYND CICS Listener specific; Needed for both CTG and SBYND CICS Listener; Also, the exposed CicsClient methods are categorized as: CTG specific, such as getServerList(); SBYND CICS Listener specific, such as prepareAPCRecord(), returnCodeIs(), returnOK(), getResponse(...) etc.; Common to both CTG and SBYND CICS Listener, such as execute(), execute(....), and sendRequest(...);


Method Summary
 PackedDecimal commAreaToPackedDecimal(int offset, int intSize, int decSize)
          Build a packed decimal from the payload in CommArea section specified by (offset, intSize, decSize)
 java.lang.String commAreaZonedToString(int offset, int length)
          Convert the zoned decimal (COBOL PIC S9) byte array CommArea field to a String using current value of CicsClient Encoding as encoding;
 java.lang.String commAreaZonedToString(int offset, int length, java.lang.String enc)
          Convert the zoned decimal (COBOL PIC S9) byte array CommArea field to a String;
 void connect()
          Establish a connection to the CICS server and subsequently, the collaboration can flow request (CICS program calls) to the server across the connection;
 void disconnect()
          Disconnect the connection established through connect();
 void execute()
          For SBYND CICS Listner:
 void execute(boolean eciSynCall, java.lang.String cicsServerName, java.lang.String cicsUserId, java.lang.String cicsPassword, java.lang.String cicsProgram, java.lang.String cicsTransId, byte[] byteArray, int length, boolean eciExtendMode, int eciLUWToken, int msgQualifier, java.lang.Object asyncCallHandler)
          if eciTPN is not in the parameter list, set it to false
 void execute(boolean eciSynCall, java.lang.String cicsServerName, java.lang.String cicsUserId, java.lang.String cicsPassword, java.lang.String cicsProgram, java.lang.String cicsTransId, byte[] byteArray, int length, boolean eciExtendMode, int eciLUWToken, int msgQualifier, java.lang.Object asyncCallHandler, boolean eciTPN)
          For SBYND CICS Listner: invoke the remote CICS program through the following steps (defined by a propritary protocol) (1) prepare a APC record (Application Control Record) with request code as SBYND_LISTENER_REQCODE_REQ_SYNC or SBYND_LISTENER_REQCODE_REQ_ASYNC depend on parameter eciSynCall with byteArray as the payload; the prepare APC record is in the outbound buffer in SBYNDCicsProxy (2) send the request to SBYND CICS Listener; (3) get response from SBYND CICS Listener; (4) further get returned data from the program if it is a sync call (5) ACK or NACK accordingly For CTG: prepare an ECIRequest object with the data given via the parameters, call method flow() to send the request and get result (sync) or proceed (async);
 byte[] getCommArea()
          Getter for CicsClient CommArea; Return the CommArea - i.e.
 int getCommAreaLength()
          Getter for CicsClient CommAreaLength; Return the CommAreaLength - i.e.
 java.lang.String getCommAreaString()
          Construct a commarea String by converting the commarea array of bytes using the platform's default character encoding.
 java.lang.String getCommAreaString(int offset, int length)
          Construct a commarea String by converting the commarea array of bytes with offset and length using the platform's default character encoding.
 java.lang.String getCommAreaString(int offset, int length, java.lang.String enc)
          Construct a commarea String by converting the commarea array of bytes with offset and length using the platform's default character encoding.
 java.lang.String getCommAreaString(java.lang.String enc)
          Construct a commarea String by converting the commarea array of bytes using the character encoding specified as an argument.
 ECIErrorCodes getECIERRORS()
          CTG specific; Return ECIErrorCodes object; this getter is for CicsClient ECIERRORS;
 boolean getEciExtend()
          Getter for CicsClient EciExtend; Return the EciExtend flag (refer to CTG doc for detailed description of the flag) - i.e.
 int getEciLuwToken()
          Getter for CicsClient EciLuwToken; Return the ECI Luw token; - i.e.
 boolean getEciSync()
          Getter for CicsClient EciSync; Return the ECI call type - i.e.
 boolean getEciTPN()
          Getter for CicsClient eciTPN; Return the ECI Transid type CTG Only;
 java.lang.String getEncodedCommAreaString()
          Construct a commarea String by converting the commarea array of bytes using the character encoding specified earlier for the CicsClientException.
 java.lang.String getEncodedCommAreaString(int offset, int length)
          Construct a commarea String by converting the commarea array of bytes with offset and length using the platform's default character encoding.
 java.lang.String getEncoding()
          Getter for CicsClient Encoding; Return the encoding which can be used to translate the data to and from the CICS program - i.e.
 java.lang.String getHost()
          Getter for CicsClient Host; Return Host pointing to the Listener to connect to - i.e.
 int getListenerTimeout()
          SBYND CICS Listener specific; Getter for Listener time out - CicsClient ListenerTimeout initial value is from configuration parameter Listener Timeout in section "SeeBeyond CICS Listener";
 int getMessageQualifier()
          Getter for CicsClient MessageQualifier; Return the MessageQualifier for ECI call - i.e.
 java.lang.String getPaddingCharacter()
          SBYND CICS Listener specific; Getter for padding character - CicsClient PaddingCharacter initial value is from configuration parameter COMMAREA Padding Character in section "SeeBeyond CICS Listener";
 java.lang.String getPassword()
          Getter for CicsClient Password; Return the CICS user password - i.e.
 int getPollingRate()
          SBYND CICS Listener specific; Getter for Listener Polling Rate - CicsClient PollingRate initial value is from configuration parameter Polling Rate in section "SeeBeyond CICS Listener";
 int getPort()
          Getter for CicsClient Port; Return the port of the host where CTG gateway or listener is to be connected to - i.e.
 java.lang.String getProgram()
          Getter for CicsClient Program; Return the CICS program name to be invoked; - i.e.
 java.lang.String getProgramName()
          SBYND CICS Listener specific; Return the program name of the response assuming a response is in the current inbound buffer; should be called immediately after getResponse();
 int getRequestCode()
          SBYND CICS Listener specific; Return the request code of the response assuming a response is in the current inbound buffer; should be called immediately after getResponse();
 SBYNDAppControlRecordRequestCodes getREQUESTCODES()
          SBYND CICS Listener specific; Return SBYNDAppControlRecordRequestCodes object; this getter is for CicsClient REQUESTCODES;
 java.lang.String getRequestDesc()
          SBYND CICS Listener specific; Return description for the request code assuming a response is in the current inbound buffer; should be called immediately after getResponse();
 boolean getResponse()
          SBYND CICS Listener specific; Read from the SBYND CICS Listener in blocking mode until timed out or get a response;
 boolean getResponse(int timeout)
          SBYND CICS Listener specific; Read from the SBYND CICS Listener in blocking mode until timed out or get a response;
 int getReturnCode()
          SBYND CICS Listener specific; Return the error code of the current response assuming a response is in the current inbound buffer; should be called immediately after getResponse();
 SBYNDAppControlRecordReturnCodes getRETURNCODES()
          SBYND CICS Listener specific; Return SBYNDAppControlRecordReturnCodes object; this getter is for CicsClient RETURNCODES;
 java.lang.String getReturnMessage()
          SBYND CICS Listener specific; Return the error text of the current response assuming a response is in the current inbound buffer; should be called immediately after getResponse();
 java.lang.String getSBYNDListenerTransID()
          SBYND CICS Listener specific; Getter for SBYND CICS Listener TransID - CicsClient SBYNDListenerTransID initial value is from configuration parameter SeeBeyond CICS Listener TransId in section "SeeBeyond CICS Listener";
 java.lang.String getServer()
          Getter for CicsClient Server; Return CICS server name where the request is sent to - i.e.
 java.lang.String[] getServerList(int maxNumSystems)
          Obtain a list of CICS servers defined: name-description pairs With SBYND Listener as the transport, only one server is returned, i.e.
 java.lang.String getSslClass()
          Getter for CicsClient SslClass; Return the SSL class for SSL authentication - i.e.
 java.lang.String getSslPassword()
          Getter for CicsClient SslPassword; Return the PASSWORD for the encrypted KeyRing class; - i.e.
 java.lang.String getStartDelay()
          SBYND CICS Listener specific; Getter for Startup delay - CicsClient StartDelay initial value is from configuration parameter Start Delay in section "SeeBeyond CICS Listener";
 java.lang.String getStartType()
          SBYND CICS Listener specific; Getter for Startup type - CicsClient StartType initial value is from configuration parameter Start Type in section "SeeBeyond CICS Listener";
 int getTPTimeout()
          SBYND CICS Listener specific; Getter for CICS program time out - CicsClient TPTimeout initial value is from configuration parameter TP Timeout in section "SeeBeyond CICS Listener";
 int getTraceDumpOffset()
          Getter for CicsClient TraceDumpOffset; Return the trace dump offset for CTG client log; - i.e.
 java.lang.String getTraceFilename()
          Getter for CicsClient TraceFilename; Return the trace file name for CTG client log; - i.e.
 int getTraceLevel()
          Getter for CicsClient TraceLevel; Return the trace level for CTG client log; - i.e.
 boolean getTraceTiming()
          Getter for CicsClient TraceTiming; Return the trace timing (time stamp) in CTG client log; - i.e.
 int getTraceTruncationSize()
          Getter for CicsClient TraceTruncationSize; Return the trace truncation size for CTG client log; - i.e.
 java.lang.String getTransId()
          Getter for CicsClient TransId; Return the CICS transId to be invoked; - i.e.
 java.lang.String getTransport()
          Gets the Transport type (Listener or Gateway)
 int getTransportTimeout()
          SBYND CICS Listener specific; Getter for TransportTimeout - CicsClient TransportTimeout initial value is from configuration parameter Transport Timeout in section "SeeBeyond CICS Listener";
 java.lang.String getUrl()
          Getter for CicsClient Url; Return URL pointing to the remote or local CICS transaction gateway to connect to - i.e.
 java.lang.String getUserId()
          Getter for CicsClient UserId; Return the CICS user id - i.e.
 boolean isConnected()
          Check if the connection is good;
 java.lang.String packedDecimalToString(PackedDecimal pd)
          Get the string from a packed decimal object;
 void prepareAPCRecord(java.lang.String progname, int appltimeout, int requestcode, int errorcode, java.lang.String errortext)
          SBYND CICS Listener specific; Prepare an APC Record in outbound buffer of SBYNDCicsProxy using the parameters and this can be send out by invoking sendRequest() subsequently;
 boolean reset()
          Resets all the attributes of the CicsClient application.
 boolean returnCodeIs(int code)
          SBYND CICS Listener specific; check if the error code in the APC record is the same as code;
 boolean returnOK()
          SBYND CICS Listener specific; check if the error code in the APC record is SBYND_LISTENER_RC_OK;
 void sendRequest(java.lang.Object request)
          For SBYND CICS Listner: Send an ACR to the listener, assuming ACR is properly prepared and is in outbound buffer; sendRequest() only send ACR, if a response is expected, need to call getResponse() sebsequently;
 void setCommArea(byte[] byteArray)
          Setter for CicsClient CommArea; set the payload into CommArea usually used by the subsequent program invoking;
 void setCommAreaLength(int i)
          Setter for CicsClient CommAreaLength; length of the CommArea; initial value is from the configuration parameter: COMMAREA Length;
 void setEciExtend(boolean b)
          Setter for CicsClient EciExtend; Have effect for CTG only; Ignored by SBYND Listener - not implemented;
 void setEciLuwToken(int i)
          Setter for CicsClient EciLuwToken; An integer identifying a LUW; initial value is from the configuration parameter: ECI LUW token in section "CICS Client"; CTG specific;
 void setEciSync(boolean b)
          Setter for CicsClient EciSync; indicate if the call will be sync or async;
 void setEciTPN(boolean b)
          Setter for eciTPN; indicate if the transid will be interpreted as ECI_TPN;
 void setEncoding(java.lang.String s)
          Setter for CicsClient Encoding;
 void setHost(java.lang.String s)
          Setter for CicsClient Host; Set Host pointing to the Listener to connect to; Listener specific;
 void setListenerTimeout(int timeout)
          SBYND CICS Listener specific; Setter for Listener Timeout - CicsClient ListenerTimeout
 void setMessageQualifier(int i)
          Setter for CicsClient MessageQualifier; Have effect for CTG only; Ignored by SBYND Listener - not implemented;
 void setPaddingCharacter(java.lang.String padcharhex)
          SBYND CICS Listener specific; Setter for padding character - CicsClient PaddingCharacter
 void setPassword(java.lang.String s)
          Setter for CicsClient Password; the CICS password needed to authenticate the user when calling the CICS program;
 void setPollingRate(int rate)
          SBYND CICS Listener specific; Setter for Polling Rate - CicsClient PollingRate
 void setPort(int i)
          Setter for CicsClient Port; Set port of the host where the CTG or listener is running;
 void setProgram(java.lang.String s)
          Setter for CicsClient Program; the CICS program to be called;
 void setSBYNDListenerTransID(java.lang.String transid)
          SBYND CICS Listener specific; Setter for SBYND CICS Listener TransID - CicsClient SBYNDListenerTransID
 void setServer(java.lang.String s)
          Setter for CicsClient Server;
 void setSslClass(java.lang.String s)
          Setter for CicsClient SslClass; CTG specific;
 void setSslPassword(java.lang.String s)
          Setter for CicsClient SslPassword; the PASSWORD for the encrypted KeyRing class; CTG specific;
 void setStartDelay(java.lang.String startdelay)
          SBYND CICS Listener specific; Setter for Startup delay - CicsClient StartDelay
 void setStartType(java.lang.String starttype)
          SBYND CICS Listener specific; Setter for Startup delay - CicsClient StartType
 void setTPTimeout(int timeout)
          SBYND CICS Listener specific; Setter for TP Timeout - CicsClient TPTimeout
 void setTraceDumpOffset(int i)
          Setter for CicsClient TraceDumpOffset;
 void setTraceFilename(java.lang.String s)
          Setter for CicsClient TraceFilename;
 void setTraceLevel(int i)
          Setter for CicsClient TraceLevel;
 void setTraceTiming(boolean b)
          Setter for CicsClient TraceTiming; CTG only;
 void setTraceTruncationSize(int i)
          Setter for CicsClient TraceTruncationSize;
 void setTransId(java.lang.String s)
          Setter for CicsClient Program; the CICS program's trans ID to be called;
 void setTransportTimeout(int timeout)
          SBYND CICS Listener specific; Setter for Transport Timeout - CicsClient TransportTimeout
 void setUrl(java.lang.String s)
          Setter for CicsClient Url; Set URL pointing to the remote or local CICS transaction gateway to connect to; CTG specific;
 void setUserId(java.lang.String s)
          Setter for CicsClient UserId;
 PackedDecimal toPackedDecimal(java.lang.String number, int intSize, int decSize)
          Build a packed decimal from a string number Convert the in String +-99999.99 in an packed decimal IBM data Flow -> Each digit is a 0..9 Numerical value last digit is the sign digit : A|C|E|F => + ; B|D => - ; the decimal point is virtual its position is defined in the second byte of dec_length
 byte[] toZoned(java.lang.String number)
          Convert a number in the form of a String to zoned decimal (COBOL PIC S9) byte array using the current value of CicsClient Encoding as the encoding;
 byte[] toZoned(java.lang.String number, java.lang.String enc)
          Convert a number in the form of a String to zoned decimal (COBOL PIC S9) byte array using the encoding specified by the parameter enc;
 java.lang.String zonedToString(byte[] zoned)
          Convert the zoned decimal (COBOL PIC S9) byte array specified by zoned to a String using current value of CicsClient Encoding as encoding;
 java.lang.String zonedToString(byte[] zoned, java.lang.String enc)
          Convert the zoned decimal (COBOL PIC S9) byte array specified by zoned to a String using the specified encoding enc;
 

Method Detail

getTransport

java.lang.String getTransport()
Gets the Transport type (Listener or Gateway)


getUrl

java.lang.String getUrl()
Getter for CicsClient Url; Return URL pointing to the remote or local CICS transaction gateway to connect to - i.e. the current value in CicsClient Url; initial value is from the configuration parameter URL in section "CICS Gateway"; CTG specific;

Returns:
the URL;

setUrl

void setUrl(java.lang.String s)
Setter for CicsClient Url; Set URL pointing to the remote or local CICS transaction gateway to connect to; CTG specific;

Parameters:
s - - the url;

getHost

java.lang.String getHost()
Getter for CicsClient Host; Return Host pointing to the Listener to connect to - i.e. the current value in CicsClient Host; initial value is from the configuration parameter URL in section "SeeBeyond CICS Listener"; Listener specific;

Returns:
the Host;

setHost

void setHost(java.lang.String s)
Setter for CicsClient Host; Set Host pointing to the Listener to connect to; Listener specific;

Parameters:
s - - the Host;

getPort

int getPort()
Getter for CicsClient Port; Return the port of the host where CTG gateway or listener is to be connected to - i.e. the current value in CicsClientException node Port; initial value is from the configuration parameter Port in section "CICS Gateway" or "SeeBeyond CICS Listener";

Returns:
the port number;

setPort

void setPort(int i)
Setter for CicsClient Port; Set port of the host where the CTG or listener is running;

Parameters:
i - - the port;

getSslClass

java.lang.String getSslClass()
Getter for CicsClient SslClass; Return the SSL class for SSL authentication - i.e. the current value in CicsClientException node SslClass; initial value is from the configuration parameter SSL KeyRing Class in section "CICS Gateway"; CTG specific;

Returns:
the full classname of the SSL KeyRing class;

setSslClass

void setSslClass(java.lang.String s)
Setter for CicsClient SslClass; CTG specific;

Parameters:
s - - the SSL class full name;

getSslPassword

java.lang.String getSslPassword()
Getter for CicsClient SslPassword; Return the PASSWORD for the encrypted KeyRing class; - i.e. the current value in CicsClientException node SslPassword; initial value is from the configuration parameter SSL KeyRing Password in section "CICS Gateway"; CTG specific;

Returns:
the SSL KeyRing Password;

setSslPassword

void setSslPassword(java.lang.String s)
Setter for CicsClient SslPassword; the PASSWORD for the encrypted KeyRing class; CTG specific;

Parameters:
s - - the pasword;

getEciSync

boolean getEciSync()
Getter for CicsClient EciSync; Return the ECI call type - i.e. the current value in CicsClientException node EciSync; initial value is from the configuration parameter ECI call type in section "CICS Client"; CTG & SBYND Listener;

Returns:
true - the call is a synchronous one, false otherwise;

setEciSync

void setEciSync(boolean b)
Setter for CicsClient EciSync; indicate if the call will be sync or async;

Parameters:
s - - the EciSync flag true the call will be a sync call false otherwise;

getUserId

java.lang.String getUserId()
Getter for CicsClient UserId; Return the CICS user id - i.e. the current value in CicsClientException node UserId; initial value is from the configuration parameter CICS UserId in section "CICS Client"; CTG & SBYND Listener;

Returns:
the CICS user id used when make a CICS call to a program on CICS server;

setUserId

void setUserId(java.lang.String s)
Setter for CicsClient UserId;

Parameters:
s - - user id;

getPassword

java.lang.String getPassword()
Getter for CicsClient Password; Return the CICS user password - i.e. the current value in CicsClientException node Password; initial value is from the configuration parameter CICS Password in section "CICS Client"; CTG & SBYND Listener;

Returns:
the CICS user password used when make a CICS call to a program on CICS server;

setPassword

void setPassword(java.lang.String s)
Setter for CicsClient Password; the CICS password needed to authenticate the user when calling the CICS program;

Parameters:
s - - the password;

getProgram

java.lang.String getProgram()
Getter for CicsClient Program; Return the CICS program name to be invoked; - i.e. the current value in CicsClientException node Program; initial value is from the configuration parameter CICS Program in section "CICS Client"; CTG & SBYND Listener;

Returns:
the CICS program to be invoked;

setProgram

void setProgram(java.lang.String s)
Setter for CicsClient Program; the CICS program to be called;

Parameters:
s - - the program name;

getTransId

java.lang.String getTransId()
Getter for CicsClient TransId; Return the CICS transId to be invoked; - i.e. the current value in CicsClientException node TransId; initial value is from the configuration parameter CICS TransId in section "CICS Client"; CTG & SBYND Listener;

Returns:
the CICS transId to be invoked;

setTransId

void setTransId(java.lang.String s)
Setter for CicsClient Program; the CICS program's trans ID to be called;

Parameters:
s - - the trans ID of the CICS program;

getEciTPN

boolean getEciTPN()
Getter for CicsClient eciTPN; Return the ECI Transid type CTG Only;

Returns:
true - the Transid field is an eci_tpn transid, false otherwise;

setEciTPN

void setEciTPN(boolean b)
Setter for eciTPN; indicate if the transid will be interpreted as ECI_TPN;

Parameters:
s - - the eciTPN flag true the TransID will be interpreted as ECI_TPN false otherwise;

getCommArea

byte[] getCommArea()
Getter for CicsClient CommArea; Return the CommArea - i.e. the current value in CicsClientException node CommArea; CTG & SBYND Listener;

Returns:
the CommArea used when invoking CICS programs;

setCommArea

void setCommArea(byte[] byteArray)
Setter for CicsClient CommArea; set the payload into CommArea usually used by the subsequent program invoking;

Parameters:
byteArray - - the payload used by the program to be invoked;

getCommAreaLength

int getCommAreaLength()
Getter for CicsClient CommAreaLength; Return the CommAreaLength - i.e. the current value in CicsClientException node CommAreaLength; initial value is from the configuration parameter COMMAREA Length in section "CICS Client"; CTG & SBYND Listener;

Returns:
the CommArea length used when invoking CICS programs (not necessarily the length of the byte array represented as CommArea);

setCommAreaLength

void setCommAreaLength(int i)
Setter for CicsClient CommAreaLength; length of the CommArea; initial value is from the configuration parameter: COMMAREA Length;

Parameters:
i - - the length;

getEciExtend

boolean getEciExtend()
Getter for CicsClient EciExtend; Return the EciExtend flag (refer to CTG doc for detailed description of the flag) - i.e. the current value in CicsClientException node EciExtend; initial value is from the configuration parameter ECI extend mode in section "CICS Client";

Have effect for CTG only; Ignored by SBYND Listener - not implemented;

Returns:
true the current call is and extension of a LUW, false otherwise;

setEciExtend

void setEciExtend(boolean b)
Setter for CicsClient EciExtend; Have effect for CTG only; Ignored by SBYND Listener - not implemented;

Parameters:
true - the current call is and extension of a LUW, false otherwise;

getEciLuwToken

int getEciLuwToken()
Getter for CicsClient EciLuwToken; Return the ECI Luw token; - i.e. the current value in CicsClientException node EciLuwToken; initial value is from the configuration parameter ECI LUW token in section "CICS Client";

Have effect for CTG only ignored by SBYND Listener - not implemented;

Returns:
current value of ECI Luw token;

setEciLuwToken

void setEciLuwToken(int i)
Setter for CicsClient EciLuwToken; An integer identifying a LUW; initial value is from the configuration parameter: ECI LUW token in section "CICS Client"; CTG specific;

Parameters:
i - - the unit;

getMessageQualifier

int getMessageQualifier()
Getter for CicsClient MessageQualifier; Return the MessageQualifier for ECI call - i.e. the current value in CicsClientException node MessageQualifier; initial value is from the configuration parameter Message qualifier in section "CICS Client";

Have effect for CTG only ignored by SBYND Listener - not implemented;

Returns:
Message qualifier;

setMessageQualifier

void setMessageQualifier(int i)
Setter for CicsClient MessageQualifier; Have effect for CTG only; Ignored by SBYND Listener - not implemented;

Parameters:
i - the message qualifier;

getEncoding

java.lang.String getEncoding()
Getter for CicsClient Encoding; Return the encoding which can be used to translate the data to and from the CICS program - i.e. the current value in CicsClientException node Encoding; initial value is from the configuration parameter Encoding in section "CICS Client";

CTG & SBYND Listener;

Returns:
the encoding;

setEncoding

void setEncoding(java.lang.String s)
Setter for CicsClient Encoding;

Parameters:
s - the encoding used for payload translation;

getTraceLevel

int getTraceLevel()
Getter for CicsClient TraceLevel; Return the trace level for CTG client log; - i.e. the current value in CicsClientException node TraceLevel; initial value is from the configuration parameter Level in section "Tracing";

CTG only;

Returns:
the trace level for CTG client;

setTraceLevel

void setTraceLevel(int i)
Setter for CicsClient TraceLevel;

Parameters:
i - the CTG client tracing level;

getTraceFilename

java.lang.String getTraceFilename()
Getter for CicsClient TraceFilename; Return the trace file name for CTG client log; - i.e. the current value in CicsClientException node TraceFilename; initial value is from the configuration parameter Filename in section "Tracing";

CTG only;

Returns:
the trace file name for CTG client;

setTraceFilename

void setTraceFilename(java.lang.String s)
Setter for CicsClient TraceFilename;

Parameters:
s - the CTG client tracing file name;

getTraceTruncationSize

int getTraceTruncationSize()
Getter for CicsClient TraceTruncationSize; Return the trace truncation size for CTG client log; - i.e. the current value in CicsClientException node TraceTruncationSize; initial value is from the configuration parameter Truncation Size in section "Tracing";

CTG only;

Returns:
the truncation size for CTG client logging;

setTraceTruncationSize

void setTraceTruncationSize(int i)
Setter for CicsClient TraceTruncationSize;

Parameters:
i - the CTG client tracing truncation size;

getTraceDumpOffset

int getTraceDumpOffset()
Getter for CicsClient TraceDumpOffset; Return the trace dump offset for CTG client log; - i.e. the current value in CicsClientException node TraceDumpOffset; initial value is from the configuration parameter Dump Offset in section "Tracing";

CTG only;

Returns:
the trace dump offset for CTG client logging;

setTraceDumpOffset

void setTraceDumpOffset(int i)
Setter for CicsClient TraceDumpOffset;

Parameters:
i - the CTG client tracing dump offset;

getTraceTiming

boolean getTraceTiming()
Getter for CicsClient TraceTiming; Return the trace timing (time stamp) in CTG client log; - i.e. the current value in CicsClientException node TraceTiming; initial value is from the configuration parameter Timing in section "Tracing";

CTG only;

Returns:
trueinclude time stamp in CTG client tracing false otherwise;

setTraceTiming

void setTraceTiming(boolean b)
Setter for CicsClient TraceTiming; CTG only;

Parameters:
b - true include time stamp in CTG client tracing, false otherwise;

getServer

java.lang.String getServer()
Getter for CicsClient Server; Return CICS server name where the request is sent to - i.e. the current value in CicsClientException node Server;

With CTG, the value can be set by the collaboration or if getServerList() is called, the side effect is to set the first server in the server list obtained to the CicsClient Server; With SBYND Listener, the value is not used; instead a configuration parameter Host in configuration section "SeeBeyond CICS Listener" is used;

Returns:
the CICS server name;

setServer

void setServer(java.lang.String s)
Setter for CicsClient Server;

Parameters:
s - CICS Server name;

reset

boolean reset()
Resets all the attributes of the CicsClient application.

Returns:
false if the CicsClientException doesn't have a meaningful implementation of reset(); so do a new of the CicsClientException instead. Otherwise, return true if the reset will clear the data content of the CicsClientException.

connect

void connect()
             throws CicsClientException
Establish a connection to the CICS server and subsequently, the collaboration can flow request (CICS program calls) to the server across the connection;

The underlying transport used can be CTG or SBYND Listener but it is transparent to the collaboration as far as the connect() is concerned;

Throws:
CicsClientException - upon an external connection problem

disconnect

void disconnect()
                throws CicsClientException
Disconnect the connection established through connect();

The underlying transport used can be CTG or SBYND Listener but it is transparent to the collaboration as far as the disconnect() is concerned;

Throws:
CicsClientException - upon an external connection problem

isConnected

boolean isConnected()
                    throws CicsClientException
Check if the connection is good;

Returns:
true - is active, false otherwise;
Throws:
CicsClientException - upon error.

getServerList

java.lang.String[] getServerList(int maxNumSystems)
                                 throws CicsClientException
Obtain a list of CICS servers defined: name-description pairs With SBYND Listener as the transport, only one server is returned, i.e. the SBYND Listener host (should be the same host as the CICS server)

Returns:
An array of servers - list of available CICS servers to which CICS call can be issued
Throws:
CicsClientException - upon an external connection problem

execute

void execute()
             throws CicsClientException,
                    SBYNDCicsProxyTimeoutException
For SBYND CICS Listner:

use SBYND CICS Listener host as the server name and delegate to execute(eciSync, server, userId, password, program, transId,commArea, commAreaLength, eciExtend, eciLuwToken, messageQualifier, asyncCallHandler) with irrelevant parameters set to 0 or null. only the following parameters are still used by SBYND CICS Listener: (1) eciSync (2) userId (3) password (4) program (5) transId (6) commArea

For CTG:

delegate to execute(eciSync, server, userId, password, program, transId,commArea, commAreaLength, eciExtend, eciLuwToken, messageQualifier, asyncCallHandler)

Throws:
CicsClientException - upon error
SBYNDCicsProxyTimeoutException

execute

void execute(boolean eciSynCall,
             java.lang.String cicsServerName,
             java.lang.String cicsUserId,
             java.lang.String cicsPassword,
             java.lang.String cicsProgram,
             java.lang.String cicsTransId,
             byte[] byteArray,
             int length,
             boolean eciExtendMode,
             int eciLUWToken,
             int msgQualifier,
             java.lang.Object asyncCallHandler)
             throws CicsClientException,
                    SBYNDCicsProxyTimeoutException
if eciTPN is not in the parameter list, set it to false

Throws:
CicsClientException
SBYNDCicsProxyTimeoutException

execute

void execute(boolean eciSynCall,
             java.lang.String cicsServerName,
             java.lang.String cicsUserId,
             java.lang.String cicsPassword,
             java.lang.String cicsProgram,
             java.lang.String cicsTransId,
             byte[] byteArray,
             int length,
             boolean eciExtendMode,
             int eciLUWToken,
             int msgQualifier,
             java.lang.Object asyncCallHandler,
             boolean eciTPN)
             throws CicsClientException,
                    SBYNDCicsProxyTimeoutException
For SBYND CICS Listner: invoke the remote CICS program through the following steps (defined by a propritary protocol) (1) prepare a APC record (Application Control Record) with request code as SBYND_LISTENER_REQCODE_REQ_SYNC or SBYND_LISTENER_REQCODE_REQ_ASYNC depend on parameter eciSynCall with byteArray as the payload; the prepare APC record is in the outbound buffer in SBYNDCicsProxy (2) send the request to SBYND CICS Listener; (3) get response from SBYND CICS Listener; (4) further get returned data from the program if it is a sync call (5) ACK or NACK accordingly For CTG: prepare an ECIRequest object with the data given via the parameters, call method flow() to send the request and get result (sync) or proceed (async);

Parameters:
eciSynCall - - true invoke the program synchronously, false invoke the program asynchronously;
cicsServerName - - CICS server name - CTG only;
cicsUserId - - CICS user id;
cicsPassword - - CICS password;
cicsProgram - - CICS program;
cicsTransId - - CICS transaction id;
byteArray - - payload area (INOUT & OUTPUT)
length - - length of the payload - CTG only;
eciExtendMode - - ECI extend mode - CTG only;
eciLUWToken - - ECI LUW token - CTG only;
msgQualifier - - CTG only;
asyncCallHandler - - Handler for async call reply;
Throws:
CicsClientException - upon error
SBYNDCicsProxyTimeoutException

getCommAreaString

java.lang.String getCommAreaString()
Construct a commarea String by converting the commarea array of bytes using the platform's default character encoding.

Returns:
the CommArea in String form;

getEncodedCommAreaString

java.lang.String getEncodedCommAreaString()
                                          throws java.io.UnsupportedEncodingException
Construct a commarea String by converting the commarea array of bytes using the character encoding specified earlier for the CicsClientException.

Returns:
the CommArea in String form using Encoding to do the translation;
Throws:
java.io.UnsupportedEncodingException

getCommAreaString

java.lang.String getCommAreaString(java.lang.String enc)
                                   throws java.io.UnsupportedEncodingException
Construct a commarea String by converting the commarea array of bytes using the character encoding specified as an argument.

Parameters:
enc - the encoding used when translating the CommArea byte array into a String;
Returns:
the CommArea as a String;
Throws:
java.io.UnsupportedEncodingException

getCommAreaString

java.lang.String getCommAreaString(int offset,
                                   int length)
Construct a commarea String by converting the commarea array of bytes with offset and length using the platform's default character encoding.

Parameters:
offset -
length -
Returns:
the String instanciated from CommArea section specified by (offset, length) using system default encoding;

getEncodedCommAreaString

java.lang.String getEncodedCommAreaString(int offset,
                                          int length)
                                          throws java.io.UnsupportedEncodingException
Construct a commarea String by converting the commarea array of bytes with offset and length using the platform's default character encoding.

Parameters:
offset -
length -
Returns:
the String instanciated from CommArea section specified by (offset, length) using encoding indicated by current value of CicsClient Encoding;
Throws:
java.io.UnsupportedEncodingException

getCommAreaString

java.lang.String getCommAreaString(int offset,
                                   int length,
                                   java.lang.String enc)
                                   throws java.io.UnsupportedEncodingException
Construct a commarea String by converting the commarea array of bytes with offset and length using the platform's default character encoding.

Parameters:
offset -
length -
enc -
Returns:
the String instanciated from CommArea section specified by (offset, length) using encoding specified by parameter enc;
Throws:
java.io.UnsupportedEncodingException

sendRequest

void sendRequest(java.lang.Object request)
                 throws CicsClientException
For SBYND CICS Listner: Send an ACR to the listener, assuming ACR is properly prepared and is in outbound buffer; sendRequest() only send ACR, if a response is expected, need to call getResponse() sebsequently;

For CTG: The sendRequest method flows data contained in the ECIRequest object to the Gateway and determines whether send has been successful by checking the return code. If an error has occurred, an CollabConnException is thrown.

Parameters:
request - - ECIRequest object contains all the data needed to invoke a CICS program through CTG, for SBYND CICS Listener this parameter is ignored;
Throws:
CicsClientException - upon error

toPackedDecimal

PackedDecimal toPackedDecimal(java.lang.String number,
                              int intSize,
                              int decSize)
                              throws java.lang.NumberFormatException
Build a packed decimal from a string number Convert the in String +-99999.99 in an packed decimal IBM data Flow -> Each digit is a 0..9 Numerical value last digit is the sign digit : A|C|E|F => + ; B|D => - ; the decimal point is virtual its position is defined in the second byte of dec_length

Parameters:
Number - decimal String representation to be converted
Returns:
the packed decimal object;
Throws:
java.lang.NumberFormatException

commAreaToPackedDecimal

PackedDecimal commAreaToPackedDecimal(int offset,
                                      int intSize,
                                      int decSize)
Build a packed decimal from the payload in CommArea section specified by (offset, intSize, decSize)

Parameters:
offset -
intSize -
decSize -
Returns:
the packed decimal object;

packedDecimalToString

java.lang.String packedDecimalToString(PackedDecimal pd)
Get the string from a packed decimal object;

Parameters:
pd -
Returns:
the String from applying toString() against the packed decimal object;

commAreaZonedToString

java.lang.String commAreaZonedToString(int offset,
                                       int length,
                                       java.lang.String enc)
Convert the zoned decimal (COBOL PIC S9) byte array CommArea field to a String;

Parameters:
offset - - start of the zone;
length - - length of the zone;
enc - - encoding used for conversion;
Returns:
the resulted String;

commAreaZonedToString

java.lang.String commAreaZonedToString(int offset,
                                       int length)
Convert the zoned decimal (COBOL PIC S9) byte array CommArea field to a String using current value of CicsClient Encoding as encoding;

Parameters:
offset - - start of the zone;
length - - length of the zone;
Returns:
the resulted String;

zonedToString

java.lang.String zonedToString(byte[] zoned)
                               throws java.lang.NumberFormatException
Convert the zoned decimal (COBOL PIC S9) byte array specified by zoned to a String using current value of CicsClient Encoding as encoding;

Parameters:
zoned - - the byte array contains zoned decimal;
Returns:
the resulted String;
Throws:
java.lang.NumberFormatException

zonedToString

java.lang.String zonedToString(byte[] zoned,
                               java.lang.String enc)
                               throws java.lang.NumberFormatException
Convert the zoned decimal (COBOL PIC S9) byte array specified by zoned to a String using the specified encoding enc;

Parameters:
zoned - - the byte array contains zoned decimal;
enc - - the encoding used for conversion;
Returns:
the resulted String;
Throws:
java.lang.NumberFormatException

toZoned

byte[] toZoned(java.lang.String number)
Convert a number in the form of a String to zoned decimal (COBOL PIC S9) byte array using the current value of CicsClient Encoding as the encoding;

Parameters:
number - - the number String;
Returns:
the resulted byte array;

toZoned

byte[] toZoned(java.lang.String number,
               java.lang.String enc)
Convert a number in the form of a String to zoned decimal (COBOL PIC S9) byte array using the encoding specified by the parameter enc;

Parameters:
number - - the number String;
enc - - the encoding;
Returns:
the resulted byte array;

getReturnCode

int getReturnCode()
                  throws CicsClientException
SBYND CICS Listener specific; Return the error code of the current response assuming a response is in the current inbound buffer; should be called immediately after getResponse();

Returns:
the error code;
Throws:
CicsClientException

getReturnMessage

java.lang.String getReturnMessage()
                                  throws CicsClientException
SBYND CICS Listener specific; Return the error text of the current response assuming a response is in the current inbound buffer; should be called immediately after getResponse();

Returns:
the error text;
Throws:
CicsClientException

getProgramName

java.lang.String getProgramName()
                                throws CicsClientException
SBYND CICS Listener specific; Return the program name of the response assuming a response is in the current inbound buffer; should be called immediately after getResponse();

Returns:
the program name;
Throws:
CicsClientException

getRequestCode

int getRequestCode()
                   throws CicsClientException
SBYND CICS Listener specific; Return the request code of the response assuming a response is in the current inbound buffer; should be called immediately after getResponse();

Returns:
the request code;
Throws:
CicsClientException

getRequestDesc

java.lang.String getRequestDesc()
                                throws CicsClientException
SBYND CICS Listener specific; Return description for the request code assuming a response is in the current inbound buffer; should be called immediately after getResponse();

Returns:
the descritpion;
Throws:
CicsClientException

prepareAPCRecord

void prepareAPCRecord(java.lang.String progname,
                      int appltimeout,
                      int requestcode,
                      int errorcode,
                      java.lang.String errortext)
                      throws CicsClientException
SBYND CICS Listener specific; Prepare an APC Record in outbound buffer of SBYNDCicsProxy using the parameters and this can be send out by invoking sendRequest() subsequently;

Parameters:
progname - - the transaction program name;
appltimeout - - application timeout not used (reserved);
requestcode - - request code of the ACR;
errorcode - - error code of the ACR;
errortext - - error message (usually used when the ACR is an NACK);
Throws:
CicsClientException - if error in data;

returnCodeIs

boolean returnCodeIs(int code)
                     throws CicsClientException
SBYND CICS Listener specific; check if the error code in the APC record is the same as code;

Returns:
true error code is the same as code, otherwise, false;
Throws:
CicsClientException

returnOK

boolean returnOK()
                 throws CicsClientException
SBYND CICS Listener specific; check if the error code in the APC record is SBYND_LISTENER_RC_OK;

Returns:
true error code is SBYND_LISTENER_RC_OK, otherwise, false;
Throws:
CicsClientException

getResponse

boolean getResponse()
                    throws CicsClientException,
                           SBYNDCicsProxyTimeoutException
SBYND CICS Listener specific; Read from the SBYND CICS Listener in blocking mode until timed out or get a response;

Returns:
true if get a good ACR otherwise, false; use the SBYND CICS Listener parameter: Transport Timeout as the timeout;
Throws:
CicsClientException
SBYNDCicsProxyTimeoutException

getResponse

boolean getResponse(int timeout)
                    throws CicsClientException,
                           SBYNDCicsProxyTimeoutException
SBYND CICS Listener specific; Read from the SBYND CICS Listener in blocking mode until timed out or get a response;

Parameters:
timeout - - timeout for getting response;
Returns:
true if get a good ACR otherwise, false;
Throws:
CicsClientException
SBYNDCicsProxyTimeoutException

getECIERRORS

ECIErrorCodes getECIERRORS()
                           throws CicsClientException
CTG specific; Return ECIErrorCodes object; this getter is for CicsClient ECIERRORS;

Returns:
ECIErrorCodes;
Throws:
CicsClientException

getRETURNCODES

SBYNDAppControlRecordReturnCodes getRETURNCODES()
                                                throws CicsClientException
SBYND CICS Listener specific; Return SBYNDAppControlRecordReturnCodes object; this getter is for CicsClient RETURNCODES;

Returns:
SBYNDAppControlRecordReturnCodes;
Throws:
CicsClientException

getREQUESTCODES

SBYNDAppControlRecordRequestCodes getREQUESTCODES()
                                                  throws CicsClientException
SBYND CICS Listener specific; Return SBYNDAppControlRecordRequestCodes object; this getter is for CicsClient REQUESTCODES;

Returns:
SBYNDAppControlRecordRequestCodes;
Throws:
CicsClientException

getSBYNDListenerTransID

java.lang.String getSBYNDListenerTransID()
                                         throws CicsClientException
SBYND CICS Listener specific; Getter for SBYND CICS Listener TransID - CicsClient SBYNDListenerTransID initial value is from configuration parameter SeeBeyond CICS Listener TransId in section "SeeBeyond CICS Listener";

Returns:
the listener trans ID - the default value is "STCL";
Throws:
CicsClientException

setSBYNDListenerTransID

void setSBYNDListenerTransID(java.lang.String transid)
                             throws CicsClientException
SBYND CICS Listener specific; Setter for SBYND CICS Listener TransID - CicsClient SBYNDListenerTransID

Parameters:
transid - - the transaction ID of the SBYND CICS Listener - STCL;
Throws:
CicsClientException

getTPTimeout

int getTPTimeout()
                 throws CicsClientException
SBYND CICS Listener specific; Getter for CICS program time out - CicsClient TPTimeout initial value is from configuration parameter TP Timeout in section "SeeBeyond CICS Listener";

Returns:
the timeout value in milli-seconds; usually this is set to the max estimated time takes the CICS program to finish and come back to the inoker;
Throws:
CicsClientException

setTPTimeout

void setTPTimeout(int timeout)
                  throws CicsClientException
SBYND CICS Listener specific; Setter for TP Timeout - CicsClient TPTimeout

Parameters:
timeout - - the timeout value in milli-seconds; usually this is set to the max estimated time takes the CICS program to finish and come back to the inoker;
Throws:
CicsClientException

getListenerTimeout

int getListenerTimeout()
                       throws CicsClientException
SBYND CICS Listener specific; Getter for Listener time out - CicsClient ListenerTimeout initial value is from configuration parameter Listener Timeout in section "SeeBeyond CICS Listener";

Returns:
the timeout value in milli-seconds; usually this is set to the time that the SBYND listener will wait for program invoking request from the eway before it close the connection;
Throws:
CicsClientException

setListenerTimeout

void setListenerTimeout(int timeout)
                        throws CicsClientException
SBYND CICS Listener specific; Setter for Listener Timeout - CicsClient ListenerTimeout

Parameters:
timeout - - the time that the SBYND listener will wait for program invoking request from the eway before it close the connection;
Throws:
CicsClientException

getPollingRate

int getPollingRate()
                   throws CicsClientException
SBYND CICS Listener specific; Getter for Listener Polling Rate - CicsClient PollingRate initial value is from configuration parameter Polling Rate in section "SeeBeyond CICS Listener";

Returns:
a 1-255 value used by listener internally;
Throws:
CicsClientException

setPollingRate

void setPollingRate(int rate)
                    throws CicsClientException
SBYND CICS Listener specific; Setter for Polling Rate - CicsClient PollingRate

Parameters:
rate - - a 1-255 value used by listener internally;
Throws:
CicsClientException

getTransportTimeout

int getTransportTimeout()
                        throws CicsClientException
SBYND CICS Listener specific; Getter for TransportTimeout - CicsClient TransportTimeout initial value is from configuration parameter Transport Timeout in section "SeeBeyond CICS Listener";

Returns:
time in milli-seconds used to timeout a blocking read on a socket between the eway and the listener;
Throws:
CicsClientException

setTransportTimeout

void setTransportTimeout(int timeout)
                         throws CicsClientException
SBYND CICS Listener specific; Setter for Transport Timeout - CicsClient TransportTimeout

Parameters:
timeout - - time in milli-seconds used to timeout a blocking read on a socket between the eway and the listener;
Throws:
CicsClientException

getStartType

java.lang.String getStartType()
                              throws CicsClientException
SBYND CICS Listener specific; Getter for Startup type - CicsClient StartType initial value is from configuration parameter Start Type in section "SeeBeyond CICS Listener";

Returns:
startup type for IBM CICS Listener - possible values "IC" or "TD";
Throws:
CicsClientException

setStartType

void setStartType(java.lang.String starttype)
                  throws CicsClientException
SBYND CICS Listener specific; Setter for Startup delay - CicsClient StartType

Parameters:
starttype - - the Startup type value either "IC" or "TD" used by IBM CICS Listener to decide how the SBYND Listener will be waked up;
Throws:
CicsClientException

getStartDelay

java.lang.String getStartDelay()
                               throws CicsClientException
SBYND CICS Listener specific; Getter for Startup delay - CicsClient StartDelay initial value is from configuration parameter Start Delay in section "SeeBeyond CICS Listener";

Returns:
IBM CICS Listener needed parameter Startup delay a string in the format of HHMMSS - indicating the time elapsed before the STCL (SBYND CICS Listener be waked up);
Throws:
CicsClientException

setStartDelay

void setStartDelay(java.lang.String startdelay)
                   throws CicsClientException
SBYND CICS Listener specific; Setter for Startup delay - CicsClient StartDelay

Parameters:
startdelay - - the delay value in the format of HHMMSS used by IBM CICS Listener to delay the wake up of SBYND listener, the default value is "000000";
Throws:
CicsClientException

getPaddingCharacter

java.lang.String getPaddingCharacter()
                                     throws CicsClientException
SBYND CICS Listener specific; Getter for padding character - CicsClient PaddingCharacter initial value is from configuration parameter COMMAREA Padding Character in section "SeeBeyond CICS Listener";

Returns:
the EBCDIC code for the character used by the SBYND listener to pad the COMMAREA at the CICS server when the actual length of the payload in the COMMAREA is shorter than the length given by CommAreaLength; the default is hexdecimal 40 - EBCDIC space;
Throws:
CicsClientException

setPaddingCharacter

void setPaddingCharacter(java.lang.String padcharhex)
                         throws CicsClientException
SBYND CICS Listener specific; Setter for padding character - CicsClient PaddingCharacter

Parameters:
padcharhex - the EBCDIC code for the character used by the SBYND listener to pad the COMMAREA at the CICS server when the actual length of the payload in the COMMAREA is shorter than the length given by CommAreaLength; the default is hexdecimal 40 - EBCDIC space;
Throws:
CicsClientException

Sun Adapter for CICS API