IccSession

Purpose

Enables APPC and DTP programming.

Synopsis

#include <iccseseh.hpp>

class  
{
protected:
       IccSession();
public:
       IccSession(const IccPartnerId&);
       IccSession(const IccSysId& sysId);
       IccSession(const char* sysName);
       void allocate(AllocateOpt option=queue);
       void connectProcess(SyncLevel level,
            const IccTransId& transId,
            const IccBuf* PIP=0);
       void connectProcess(syncLevel level,
            const IccTPNameId& TPName,
            const IccBuf* PIP=0);
       const IccBuf& converse(const IccBuf& send);
       const IccConvId& convId();
       const char* errorCode() const;
       void extractProcess();
       void flush();
       void free();
       virtual const IccBuf& get();
       Icc::Bool isErrorSet() const;
       Icc::Bool isNoDataSet() const;
       Icc::Bool isSignalSet() const;
       void issueAbend();
       void issueConfirmation();
       void issueError();
       void issueSignal();
       IccBuf& PIPList();
       const IccBuf& process() const;
       virtual void put(const IccBuf& data);
       const IccBuf& receive();
       void send(const IccBuf& send,
            SendOpt option=normal);
       void send(sendOpt option=normal);
       void sendInvite(const IccBuf& send,
            SendOpt option=normal);
       void sendInvite(SendOpt option=normal);
       void sendLast(const IccBuf& send,
            SendOpt option=normal);
       void sendLast(SendOpt option=normal);
       IccValue::CVDA state(StateOpt option=lastCommand);
       const char* stateText(StateOpt option=lastCommand);
       SyncLevel syncLevel() const;
       type enum {
            queue,
            noQueue,
       } AllocateOpt,
       type enum {
            normal,
            confirmation,
            wait,
       } SendOpt;
       type enum {
            lastCommand,
            extractState,
       } StateOpt;
       type enum {
            level0,
            level1,
       } SyncLevel;
};

Description

The IccSession class enables APPC and DTP programming.

Class Members

IccSession constructor

protected IccSession();

This constructor is for back end DTP CICS® tasks that have a session as their principal facility. In this case, the application program uses the session method on the IccControl object to gain access to their IccSession object.

IccSession constructor (1)

IccSession(const IccPartnerId&);

IccSession constructor (2)

IccSession(const IccSysId& sysId);

sysId: A reference to an IccSysId object that represents a remote CICS system.

IccSession constructor (3)

IccSession(const char* sysName);

sysName: The four-character name of the remote CICS system with which this session is associated.

IccSession::allocate

void allocate(AllocateOpt option=queue);

option: An enumeration, which defined in this class, that indicates what action CICS is to take if a communication channel is unavailable when this method is called.

This method establishes a session (communication channel) to the remote system.

Equivalent EXEC CICS call: ALLOCATE

Conditions: INVREQ, SYSIDERR

IccSession::connectProcess (1)

void connectProcess(SyncLevel level,
     const IccTransId& transId,
     const IccBuf* PIP=0);

level: An enumeration, which is defined in this class, that indicates what sync level is to be used for this conversation.

transId: A reference to an IccTransId object that holds the name of the transaction that is to be started on the remote system.

PIP: An optional pointer to an IccBuf object that contains the PIP data that is to be sent to the remote system.

Equivalent EXEC CICS call: CONNECT PROCESS CONVID

IccSession::connectProcess (2)

void connectProcess(SyncLevel level,
     const IccTPNameId& TPName,
     const IccBuf* PIP=0);

level: An enumeration, which is defined in this class, that indicates what sync level is to be used for this conversation.

TPName: A reference to an IccTPNameId object that contains the 1 through 64 character TP name.

PIP: An optional pointer top an IccBuf object that contains the PIP data that is nto be sent to the remote system.

This method starts a partner process on the remote system in preparation for sending and receiving information.

Equivalent EXEC CICS call: CONNECT PROCESS CONVID

Conditions: INVREQ, LENGERR, NOTALLOC, CBIDERR (Open Systems only), SYSIDERR (Open Systems only), SYSBUSY (Open Systems only)

IccSession::converse

const IccBuf& converse(const IccBuf& send);

send: A reference to an IccBuf object that contains the data that is to be sent.

This method sends the contents of send and returns a reference to an IccBuf object that holds the reply from the remote APPC partner.

Equivalent EXEC CICS call: CONVERSE CONVID

Conditions: INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

IccSession::convId

const IccConvId& convId();

This method returns a reference to an IccConvId object that contains the four-byte conversation identifier.

IccSession::errorCode

const char* errorCode() const;

This method returns the four-byte error code that is received when isErrorSet remains true. See the relevant DTP Guide for more information.

IccSession::extractProcess

void extractProcess();

This method retrieves information from an APPC conversation attach header and holds it inside the object. See PIPList, process, and syncLevel methods to retrieve the information from the object. This method should be used by the back end task if it wants access to the PIP data, the process name, or the synclevel under which it is running.

Equivalent EXEC CICS call: EXTRACT PROCESS CONVID

Conditions: INVREQ, NOTAUTH

IccSession::flush

void flush();

This method ensures that accumulated data and control information are transmitted on an APPC mapped conversation.

Equivalent EXEC CICS call: WAIT CONVID

Conditions: INVREQ, NOTALLOC

IccSession::free

void free();

This method returns the APPC session to CICS so that it can be used by other tasks.

Equivalent EXEC CICS call: FREE CONVID

Conditions: INVREQ, NOTALLOC

IccSession::get

virtual const IccBuf& get();

This method is a synonym for receive. See Polymorphic behavior for more information about polymorphism.

IccSession::isErrorSet

Icc::Bool isErrorSet() const;

This method returns a Boolean variable, which is defined in Icc structure, that indicates whether an error has been set.

IccSession::isNoDataSet

Icc::Bool isNoDataSet() const;

This method returns a Boolean variable, which is defined in Icc structure, that indicates if no data was returned on a send; only control information.

IccSession::isSignalSet

Icc::Bool isSignalSet() const;

This method returns a Boolean variable, which is defined in Icc structure, that indicates whether a signal has been received from the remote process.

IccSession::issueAbend

void issueAbend();

This method abnormally ends the conversation. The partner transaction sees the TERMERR condition.

Equivalent EXEC CICS call: ISSUE ABEND CONVID

Conditions: INVREQ, NOTALLOC, TERMERR

IccSession::issueConfirmation

void issueConfirmation();

This method sends positive response to a partner's send request that specified the confirmation option.

Equivalent EXEC CICS call: ISSUE CONFIRMATION CONVID

Conditions: INVREQ, NOTALLOC, TERMERR

IccSession::issueError

void issueError();

This method signals an error to the partner process.

Equivalent EXEC CICS call: ISSUE ERROR CONVID

Conditions: INVREQ, NOTALLOC, TERMERR

IccSession::issueSignal

void issueSignal();

This method signals that a mode change is needed.

Equivalent EXEC CICS call: ISSUE SIGNAL CONVID

Conditions: INVREQ, NOTALLOC, TERMERR

IccSession::PIPList

IccBuf& PIPList();

This method returns a reference to an IccBuf object that contains the PIP data that is sent from the front end process. A call to this method should be preceded by a call to extractProcess on back end DTP processes.

IccSession::process

const IccBuf& process() const;

This method returns a reference to an IccBuf object that contains the process data that is sent from the front end process. A call to this method should be preceded by a call to extractProcess on back end DTP processes.

IccSession::put

virtual void put(const IccBuf& data);

data: A reference to an IccBuf object that holds the data that is to be sent to the remote process.

This method is a synonym for send. See Polymorphic behavior for more information about polymorphism.

IccSession::receive

const IccBuf& receive();

This method returns a reference to an IccBuf object that contains the data that is received from the remote system.

Equivalent EXEC CICS call: RECEIVE CONVID

Conditions: INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

IccSession::send (1)

void send(const IccBuf& send,
     SendOpt option=normal);

send: A reference to an IccBuf object that contains the data that is to be sent.

option: An enumeration, which is defined in this class, that affects the behavior of the send method. The default is normal.

Equivalent EXEC CICS call: SEND CONVID

IccSession::send (2)

void send(sendOpt option=normal);

option: An enumeration, which is defined in this class, that affects the behavior of the send method. The default is normal.

This method sends data to the remote partner.

Equivalent EXEC CICS call: SEND CONVID

Conditions: INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

IccSession::sendInvite (1)

void sendInvite(const IccBuf& send,
     SendOpt option=normal);

send: A reference to an IccBuf object that contains the data that is to be sent.

option: An enumeration, which is defined in this class, that affects the behavior of the send method. The default is normal.

Equivalent EXEC CICS call: SEND CONVID INVITE

IccSession::sendInvite (2)

void sendInvite(sendOpt option=normal);

option: An enumeration, which is defined in this class, that affects the behavior of the sendInvite method. The default is normal.

This method sends data to the remote partner and indicates a change of direction; that is, the next method on this object will be receive.

Equivalent EXEC CICS call: SEND CONVID INVITE

Conditions: INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

IccSession::sendLast (1)

void sendLast(const IccBuf& send,
     SendOpt option=normal);

send: A reference to an IccBuf object that contains the data that is to be sent.

option: An enumeration, which is defined in this class, that affects the behavior of the sendLast method. The default is normal.

Equivalent EXEC CICS call: SEND CONVID LAST

IccSession::sendLast (2)

void sendLast(sendOpt option=normal);

option: An enumeration, which is defined in this class, that affects the behavior of the sendLast method. The default is normal.

This method sends data to the remote partner and indicates that this is a final transaction. The free method must be invoked next, unless the sync level is 2, when you must commit resource updates before the free. See commitOUW in IccTask class for more information.

Equivalent EXEC CICS call: SEND CONVID LAST

Conditions: INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

IccSession::state

IccValue::CVDA state(StateOpt option=lastCommand);

option: An enumeration, which is defined in this class, that indicates how to report the state of a conversation.

This method returns a CVDA, as defined in IccValue structure, that indicates the current state of the APPC conversation. Possible values are:

ALLOCATED
CONFFREE
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND
NOTAPPLIC

IccValue::NOTAPPLIC is returned if no APPC conversation state exists.

Equivalent EXEC CICS call: EXTRACT ATTRIBUTES

Conditions: INVREQ, NOTALLOC

IccSession::stateText

const char* stateText(StateOpt option=lastCommand);

option: An enumeration, which is defined in this class, that indicates how to report the conversation.

This method returns the symbolic name of the state that state method would return. For example, if state returns IccValue::ALLOCATED, stateText would return ALLOCATED.

IccSession::syncLevel

SyncLevel syncLevel() const;

This method returns an enumeration, which is defined in this class, that indicates the synchronization level that is being used in this session. A call to this method should be proceeded by a call to extractProcess on back end DTP processes.

IccSession::AllocateOpt

type enum {
     queue,
     noQueue,
 } AllocateOpt;

queue: If all available sessions are in use, CICS is to queue this request (and block the method) until it can allocate a session.

noQueue: Control is returned to the application if it cannot allocate a session. CICS raises the SYSBUSY condition.

This enumeration indicates whether queueing is required on an allocate method.

IccSession::SendOpt

type enum {
     normal,
     confirmation,
     wait,
 } SendOpt;

normal: The default.

confirmation: Indicates that a program that is using SyncLevel level1 or level2 requires a response from the remote partner program. The remote partner can respond positively, by using the issueConfirmation method, or negatively, by using the issueError method. The sending program does not receive control back from CICS until the response is received.

wait: Requests that the data is sent and not buffered internally. CICS is free to buffer requests to improve performance if this option is not specified.

IccSession::StateOpt

type enum {
     lastCommand,
     extractState,
} StateOpt;

lastCommand: Return the state at the time of the completion of the last operation on the session.

extractState: Return the explicitly extracted current state.

IccSession::SyncLevel

type enum {
     level0,
     level1,
} SyncLevel;

level0: Sync level 0 (zero).

level1: Sync level 1.

Related Information

IccBase class

IccBuf class

IccConvId class

IccPartnerId class

IccResource class

IccSysId class

IccTask class

IccTPNameId class

IccTransId class

IccValue class