Chapter 4   Server-Side API Communication


This chapter describes Connector-to-CICS communications and the API you can use to communicate from iPlanet Application Server for CICS to an connector.

---

Note	This chapter is relevant only if your CICS program is not DPL-compliant.

---

This chapter contains the following sections:

• Connector-to-CICS Communication API

• How the Communication API Works

• The Connection Record

• Protocol Examples

Connector-to-CICS Communication API

---

iPlanet Application Server Enterprise Connector for CICS comes with an Connector-to-CICS communication API that enables standard CICS applications to directly interact with the application server.

Modifications are necessary when the desired application does not follow the DPL (Distribution Program Link) guidelines, and combines user interface with business logic. iPlanet Application Server for CICS provides an API to write more advanced applications that conduct full conversations with an application.

For applications that combine user interface, replace user interface call (send and receive maps) with calls to the API to send and receive a buffer from the application server.

If you want to write a program within the server application in a CICS system that:

• receives data from the application server

• performs a task

• returns data to the application server

The application server

• makes a decision based on received data

• sends more data to that server.

A full conversation ensues with each side receiving and sending information.

To fully envision the above example, consider a band transfer at an automatic teller. The remote unit converses with the mainframe by sending and receiving information. The mainframe responds by receiving and sending back information.

The API described in this chapter is used to convert, converse, and communicate with an application server.

How the Communication API Works

---

The communication API deals with client and servers (requester and responder). In our case the Relay acts as a client and the user-server application acts as the server.

The application that initiates communication via the communication API is defined as the client application. when a client application initiates a call to remote service, the communication API starts the service application on the remote platform and manages an APPC or TCP/IP session in order to conduct the conversation.

In IAs for CICS, the Relay acts as the client in the protocol, and the CICS server applications act as the server.

Figure 4-1   

How the Communication API Works

A Simple Conversation

The client application calls the remote procedure in the same manner as it would call a local procedure. When the client application regains control, the result of the procedure call is returned to it and the service application is terminated.

Figure 4-2   

A Simple Conversation

An Advanced Conversation

The client application calls the remote procedure as it would call a local procedure. The remote procedure then stays active and a logical conversation is conducted between the client and service applications, until it is terminated by one of the partners.

The logical conversation is conducted using a protocol that is in one of the following states:

• The client application is sending data and the service application is receiving.

• The service application is sending data and the client application is receiving.

• the conversation is reset, i.e., it has ended or has not yet started.

The interface between the applications and the communication API is conducted through a connection record which contains all of the parameters used for conducting a remote procedure call and the data passed between the application.

The client application uses communication record to specify which remote application it requests to call. The location and characteristics of the service applications are read from an external-application table which contains the names and characteristics of applications.

In addition to session management, the communication API provides the services for client and service applications listed in the following table.

Table 4-1 Services Provided by the Communication API for Client and Service Applications

Service	Details
Translation	The communication API will, when requested, automatically translate data from ASCII to EBCDIC, or from EBCDIC to ASCII. The communication API, with data marshalling capabilities, translates any structure of data; taking into account the character representation (ASCII - EBCDIC) and the integer representation (big and little endian).
Error Recovery	When an error occurs, the communication API automatically cleans up the session and returns error codes to the applications so that the applications will nor remain hung-up on the conversation after the session is abended.
Data Integrity	On platforms that have recoverable databases, the communication API provides a recovery protocol that is started at session-initiation time to restart service applications in order for them to complete their transactions. This is performed every time a conversation is abended in the in-doubt period of communications.
Directory Services	The communication API directory services provide the physical attributes of remote client and server applications. These contain everything that is needed to converse with a remote application, e.g. remote location, architecture, the protocol to be used for communication, debugging options, and data-transfer options.
Standard SYNCPOINT	On platforms that support the APPC SYNCPOINT level, currently only CICS, the communication API issues the normal SYNCPOINT request to ensure database synchronization.
Chaining	A service application that is started by a client may also start its own services in order to access applications on other platforms.
Distributed Services	Multiple services may be started concurrently. an application can conduct multiple conversations at any given time.
Data Compression and/or Encryption Services	Data may optionally be compressed and/or encrypted before being sent to the remote application.

The Connection Record

---

The connection record serves as an interface between the application and the communication API. The record consists of protocol data that is used by the communication API to communicate with the remote application, and a user data buffer which is provided by the application for input and output of information from the remote application. The connection record format is used by client and service applications although the roles of the fields are not always the same.

The communication record must be initialized according to the operation being requested from the communication API. The following table specifies the format of the connection record. For information about the specific format for your environment see the sections on calling the communication API.

In the communication API there are two versions of the connection record: 1.1 and 2.0. The following table specifies the format of the connection record version 2.0

Table 4-2 Formats of the Connection Record, version 2.0

Field Name	Format (Characters)	Description
version	2	Specifies the version of the communication API with which this application has been designed to function. The purpose of the field is to enable old applications to work with new versions of the communication API that reside on remote platforms.
runmode	1	Used by the communication API client applications to force the server application to trace regardless of what the debug parameter in the directory service states. In order to turn tracing on for the service application, a "2" must be entered into the runmode field. Otherwise this field must be a character `0'. valid values are: 11 - Connection record structure format is suitable to v1.1 specification. 20 - Connection record structure format is suitable to v2.0 specifications.
storage	4	Used as a conversation handle to be kept by the application. This field must be set to null (hex `00'), before the first call in a conversation. The communication API returns a conversation ID as a four byte hexadecimal value. The value of this field must be saved and used in all subsequent calls to the same conversation. The field should be set to zero and should not be altered for the duration of the conversation.
applid	64	Field used by the client application when it first initiates a conversation to identify the service application that is to initiated on the remote platform. The entry for applid is looked up in the local directory service or directory service by the communication API. If will find the location of the service application and other parameters that are needed to start it. The applid field must be entered in the first call by the client application. This applid field is also used by a service application to obtain the start-up parameters for itself. The directory service parameters can be: whether to trace or not.
destnode	64
service	64
userid	16	The userid field is used by the client application in conjunction with the password to validate conversation level security with the service application. In addition, the userid and password are supplied as an optional security exist on the CICS side which can validate the incoming security information with any proprietary security system.
password	16	The password is recognized by the remote security system for the userid.
applreq	2	The request field is used by the application programmer to specify the operation that is to be performed by the communication API. The application requests must conform to the protocol specified in the table ..... these requests specify what should be done with the connection record currently passed to the communication API.
rc	2	The rc field is used by the communication API upon return to the application to specify the return code of the last request. The return code should be examined by the application before issuing the next request.
applind	2	this field is used by the communication API to specify the new conversation state upon return to the application. the value of the field can then be used by the application to determine its next request. The value of the field in each state can be obtained in the table .....
datatype	1	This field is used by the application to specify what kind of data it is sending in the data portion of the connection record. This is used by the communication API on the side of the service platform to convert the data to the local format when applicable, i.e. ASCII data arriving on an IBM mainframe is automatically converted to EBCDIC. The following are valid datatype values: 0 - Binary data will not be translated by the communication API; a zero must be used for marshalling. when using data marshalling this field must be set to zero so that the communication API will not translate the data. The data will be translated by a marshalling stub created by the communication API IDL compiler. 1 - Data is ASCII. 2 - Data is EBCDIC.
actlen	4 byte integer	This field is used by the application to specify the length of the data that is to be sent to he remote application. This value must be less that or equal to the buflen value. The communication API uses this field to specify to a receiving application the actual size of the data received from the remote application. This field is not used with marshalling.
buflen	4 byte integer	This field is used to specify the length of the data buffer that is passed to the communication API. Note that the data buffer is used for input and output in some requests. this means that the data buffer must accommodate the maximum length of data sent or received. If, for received data the actual data length is larger than the value supplied, the communication API will return a corresponding return code and will truncate incoming data. the field is not used with marshalling. Note - The maximum value for buflen is 32500 bytes.
data		The data field i used as an input/output area between the conversing applications. Note that the data buffer is used for input and output in some requests. In such operations the data sent to the remote application is overwritten by the incoming data. The meaning of the data in the data portion of the connection record is totally transparent to the communication API which will only change the data representation when applicable (see datatype field). this field is not used with marshalling. In an IBM mainframe environment this field is a normal character field of the length described by buflen. On PC and UNIX machines this is a pointer to a field. In such a case, the buflen field specifies the length of the buffer pointed to by that same pointer, not the length of the pointer itself which is normally 4 bytes.

The RPC Protocol States

The protocol implemented by the communication API is designed to provide simplicity for application programmers when they develop a conversation.

The conversation is started by the client application from an inactive state. The client application's first call to the communication API identifies the service application and other conversation parameters. The first call starts the service application on the remote platform, if it has not already been started. The conversation then continues until one of the applications stops it either normally or abnormally; at which point the conversation enters the E state.

After each call to the communication API the new state of the conversation is returned in the applind field of the connection record. One of the following values of applind will be returned after every successful call to the communication API"

• M - the conversation is in M state.

• S - The conversation is in S state.

• E - the conversation was ended.

  
  

  ---

  Note	A "successful call" is a call that has an "rc" of zero. In cases where the return code ends with a value of "82" (non-blocking operation), the state field is not changes' therefor its value is not valid.

  ---

  
  

The client and service applications must adhere to the rules of each state as they are described in this chapter.

The following table defines the three states of the protocols.

Table 4-3 States of the Protocol

|State	Description
E	The conversation is inactive; either the conversation has not yet started or it has already ended. The E state is a final state and in order to leave the E state the client application must start a new conversation.
M	The client application can send data and the service application must receive data. When in M state the client application is in control of the conversation.
S	The service application can send data and the client application must receive data. When in S state the service application is said to be in control of the conversation.

Client Application Requests

The client application is always the initiator of a conversation. Similar requests are issued when the conversation is in E and M states. The E state for the client application is a form of the M state. The following table describes the application requests that can be issued when the client is in either E or M states.

Table 4-4 Client Application Requests

State	Description
ML	The client application is sending data to the service application in the data portion of the connection record. The conversation will then change direction and the service application is expected to return data. When returning from an ML call, the data portion of the connection record will contain the reply from the service application. This amounts to a remote procedure call. It is important to check the new state in the applind field after this request if the programmer is not sure whether the service application has more data to send. If the state has changed to S, the service application has not relinquished control and will send more data. If the state remained M, the service application has replied with an SL request, meaning that the client application is back in control of the conversation. If the state has changed to E, the service application has replied with an SE request, which means that the service application has sent back data and ended the conversation from the service side.
M	The client application is sending data to the service application in the data portion of the connection record. After the call, the conversation will always remain in the M state, and no data will be returned from the service application since the client has more to send. With a series of M requests, the client can pass a series of records to the service application before asking for a reply.

The following request is allowed only when the conversation has not started yet; is in E state.

Table 4-5 Conversation has not started (E state)

State	Description
ME	The client application is sending data to the service application in the data portion of the connection record. After the call the conversation will always return to the E state. If the operation ended successfully, the data portion of the connection record will contain the reply from the service application. The applreq was designed to provide a true RPC interface; the client application uses only one call to initiate, send data, and receive the response from the service application. The ME operation is equivalent to an ML request followed by an E request which is used to end the conversation.

The following requests are allowed only when the client application is sending data to the service application; conversation is in the M state.

Table 4-6 Client Application is Sending Data to the Service Application

State	Description
E	The client application requests a normal end to the conversation. The conversation can end normally only from the M state and only by the client application. If the conversation uses one of the bilateral update mechanisms, commit processing is performed when the E request is issued. After an E request is processed successfully, the conversation is reset and enters the E state.
Q	The client application requests to abnormally end the conversation. The client can end the conversation only from the M state. If the conversation uses one of the bilateral update mechanisms, blackout processing is performed when the Q request is issued. After a Q request is processed successfully, the conversation is reset and enters the E state. Note: A Q call abruptly ends the conversation and the remote application may receive either a "49" or "92" return code. This means that the communication connection is closed, responding as if it was a communication error.

The following request is only allowed when the client is expecting to receive data; in the S state.

Table 4-7 Client is Expecting to Receive Data

State	Description
S	The client application is requesting to receive data from the service application. After the request is completed the data buffer will contain data from the service application. It is important to check the new state in the applind field after this request if the programmer is not sure whether the service application has more data to send. If the state remains S, the service application has not relinquished control and will send more data. If the state has changed to M, he service application has replied with an SL request, meaning that control of the conversation has been returned to the client application. If the state has changed to E, the service application has replied with an SE request. This means that the service application has send back data and ended the conversation from the service side.

The following table summarizes the requests that are allowed in each state, and the possible resulting states after the call is completed.

Table 4-8 Summary of States and Results

State	Request	State Change
E	ME	Returns to E state.
	ML	Either M, S or E depending on the service application reply.
	M	Go to M state.
M	ML	Either M or S depending on the service application reply.
	M	Remain in M state.
	E	Conversation ended - E state
	Q	Conversation ended abnormally - E state.
S	S	Either M, S or E depending on the service application reply.

Service Application Request

The service application is either initiated by the communications layer of the communication API, in which case it is an automatic responder, or the service application can start on its own and wait for incoming requests. In such a case it is called a "persistent responder". Nevertheless, the protocol that the service application uses is always the same. The conversation for the service application begins in the E state as for the client application. The E state is almost the same as the M state and differs only in the fields of the connection record that should be filled.

---

Note	When the new state depends on the service application, it depends on what applreq was used by the service application. If an SL request was issued the new state is M. When an S request is issued, the new state is S.

---

The following application request can be issued when the service is in either E or M states.

Table 4-9 Application Request when Service is either E or M

State	Description
M	The service application is requesting to receive data from the client application. After the request is completed the data buffer will contain data from the client application. It is important to check the new state in the applind field after this request if the programmer is not sure whether the client application has more data to send. If the state remains M, the client application has not relinquished control and will send more data. If the state has changed to S, the client application has issued an ML request (or ME request) meaning that the service application is now in control of the conversation. If the state has changed to E, the client application has issued an E request.

The following requests are only allowed when the conversation is in the S state.

Table 4-10 Requests Allowed When the Conversation is in the S State

State	Description
SL	The service application is sending data to the client application in the data portion of the connection record. The conversation will then change direction and the client application is expected to return data. When returning from an SL call the data portion of the connection record will contain the reply from the client application is a reply exists. It is important to check the new state in the applind field after this request if the programmer is not sure whether the client application has more data to send. If the data has changed to M, the client application has not relinquished control and will send more data. If the state remained S, the client application has replied with an ML meaning that the client application is back in control of the conversation. If the state is E, and rc is zero, the client application has normally ended the conversation.
S	The service application is sending data to the client application in the data portion of the connection record. After the call the conversation will always remain in the S state and no data will be returned from the client application since the service has more to send. With a series of S requests, the service can pass a series of records to the client application before asking for a reply.
SE	The service application is sending data to the client application in the data portion of the connection record. The conversation will then end normally and no data is expected to return. If the return code is zero, the conversation has ended. The state after an SE request is always E.
E	The service application requests a normal end to the conversation. The conversation can end normally only from the S state. After an E request is processed successfully, the conversation is reset and enters the E state.
Q	The service application requests to abnormally end the conversation. The service can end the conversation only from the S state. If the conversation uses one of the bilateral update mechanisms, blackout processing is performed when the Q request is issued. After a Q request is processed successfully, the conversation is reset and enters the E state.

The following table summarizes the requests that are allowed in each state and the possible resulting states after the call is completed.

Table 4-11 Requests Allowed in Each State and Possible Resulting States after Call

State	Request	State Change
M	M	Either M, S or E.
E	M	Either M or S.
S	SL	Either M, S or E depending on the client application reply.
	S	Remain in S state.
	E	E state - conversation ended normally.
	Q	E state - conversation ended abnormally.
	SE	E state - conversation ended abnormally.

Connection Record Field Usage

The tables below specify connection record field usage in the communication API calls. Each side, client and service, is specified in two tables: the first table specifies which fields can be used for input and the second table specifies which fields are used for output when the request is completed.

---

Note	When the new state depends on the client application, it depends on what applreq was used by the client application. The new state is S if an ML was issued. The new state is M when M is issued. The state is E when SE or E are issued.

---

Table 4-12 Connection Record Field Usage Conventions

Convention	Definition
Mandator	A value must be entered into a field.
Optional	A value may be entered into a field.
Null	Binary zeros.
(blank)	Not applicable, can be ignored.
(value)	A value is returned after a call.
Unchanged	Value should not be changed, after a previous call.
Any explicit value must be entered

The following table summarizes which fields must be set up for every client request. The first column specifies the special case where the request is issued in the E state.

Table 4-13 Client Request Field Settings

Field	1st/ME	M	ML	S	E	Q
Version	11 or 20
runmode	0 or 2			Unchanged
storage	null	Unchanged
applid	Mandatory
destnode	Optional
service	Optional
userid	Optional
password	Optional
applreq	M/ML/ME	M	ML	S	E	Q
rc
applind
datatype	0/1/2	0/1/2	0/1/2
actlen	Mandatory
buflen	Mandatory
data	Mandatory

The following table summarizes which fields returns relevant values after each client request.

Table 4-14 Field Returns after Client Request

Field	1st/ME	M	ML	S	E	Q
Version	11
runmode
storage
applid
destnode
service
userid
password
applreq
rc	Value
applind	E	M	S/M/E	S/M/E	E	E
datatype
actlen	Value		Value
buflen
data	Data		Data	Data

The following table summarizes which fields should be initiated for every service request. The first column in the table specifies the special case where the request is issued in the E state.

Table 4-15 Field That should be Initiated for Every Service Request

Field	1st/ME	M	S	SL	Q
Version	11
runmode	null	Unchanged
storage	null	Unchanged
applid	Optional
destnode
service
userid
password
applreq	M	M	S	SL	Q
rc
applind
datatype			0/1/2	0/1/2
actlen			Mandatory
buflen	Mandatory
data			Optional

The following table summarizes which fields return relevant values after every service request

Table 4-16 Field That Returns Relevant Values After Every Service Request

Field	1st/ME	M	S	SL	Q
Version	20
runmode
storage
applid
destnode
service
userid
password
applreq
rc	Value
applind	M/S/E	M/S/E	S	M/S/E	Q
datatype
actlen	Value	Value		Value
buflen
data	Data	Data		Data

Protocol Examples

---

The communication API application interface is very simple and easy to use. The following examples illustrate the protocol as discussed previously. These examples are valid in all environments, however there are some environmental specific considerations which are described in the implementation sections of this manual.

Example 1: A Simple Conversation

The client application calls a service application on a remote system with a request. After the call is completed the data field of the connection record contains the reply to the request. The whole conversation is conducted from the client application in one call and from the service application in two. In this case the protocol is transparent to the application programmer and there is no need to check the applind field at all.

Figure 4-3    A Simple Conversation

The client application calls the communication API with an ME, indicating that the service application is SRVI and provides the request in the data field of the connection record (D1). The service application is initiated and immediately calls the communication API with an M in the applreq (this is the only thing that the service application can do in the E state). The communication API returns to the service application with the request data (D1) and with the indication S, meaning that the service application is now the sender.

The service application now processes the request and calls the communication API with the response (R1) in the data field and the applreq SL, meaning that conversation control should return to the client application. This again is the only option allowed for the ME sequence. The communication API now returns to the client application and to the service application with the applind indicating an E state (conversation is over). In the data field of the client application, the communication API returns the response R1.

When the client application issues an ME from the E state, the sequence described above is the only one possible.

Example 2: A Flip-flop Conversation

The client application issues a series of remote procedure calls. Each procedure call might contain a request. When returning from each procedure call the reply to the request is available in the data field of the connection record.

Figure 4-4    A Flip-flop Conversation

The client application starts the conversation with an ML request which is the same as ME except that the conversation is not automatically ended. The service application is initiated and, as always, issues an M request. the service application receives the first data (D1) and an applind indicating that it is in the S state. The service application then issues an SL request with the response to D! (R1). when the client application gets control back, it returns to the M state. The whole process can then be repeated. In this case, when the client and service applications obtain control they are always in control of the conversation. When the client application has no more requests, it issues the applreq E, at which point the communication API responds with an applind E to both sides of the conversation.

Example 3: A Multi-record Request With One Reply

The client application sends a series of request records and obtains the reply when it issues an ML request at the end of the series.

there is no data returned as a result of the M requests.

Figure 4-5    A Multi-record Request With One Reply

The client application issues a series of M requests. The first M request differs from the others only by the usage of the connection record fields. The loop of M requests end with an ML request. The service application must match each M request with its own M request. When the client application issues an ML request the service application finds this out by finding an S state in the applind field. The service application is then in control and issues an Se request which passes the response R1 in the data field. the communication API then indicates to the client application that the conversation has ended with an E state. The client application regains control when control is returned to it and issues an E request to end the conversation.

The previously described scenarios are just examples. Any combinations of the protocol are valid as long as they stay within the rules specified in this chapter. When designing client and service applications, the protocol used should be coordinated on both sides. Although the communication API is called differently on different platforms such as UNIX, PC and Legacy systems, the requests and indications used are the same. This will make it easier to coordinate the protocol on different platforms.

In CICS, the Connector-to-CICS communication API is called by linking to a program with the connection record in the COMAREA. There are two programs which can be linked-to in order to communicate through Connector-to-CICS communication API:

• SRVRQRPC - Provides services for client applications.

• SRVRSRPC - Provides services for service applications.

  
  

  ---

  Note	Under CICS only the blocking interface is available.

  ---

  
  

Under CICS the primary facility (terminal) of a client application is the one from which it is started depending on the user. A normal CEDF can be used for debugging such applications. the primary facility of service applications is the connection. Service applications are started by APPC and usually link to Connector-to-CICS communication API to get the first request. To debug the application, the following command should be issued in CICS:

CEMT I CONN

When a connection is operational it should be in ACQ and INS states, otherwise the connection is not logged correctly. In order to see the reason why a connection has failed to logon, the CICS log and Netview information can help. In case of difficulty, notify the system and network support at your installation site.

When a service is started from the connection and a CEDF is issued, the issuing terminal will run a CEDF session in a normal manner. When debugging a conversation in this manner, all conversations on this session will be monitored. this may cause considerable confusion on the debugging terminal since all CEDF screens from different transactions will appear on the debugging terminal simultaneously. It is therefore advisable to debug conversations when running standalone on a certain connection.

The following sequences show how a programmer might prepare a connection record for the first call to Connector-to-CICS communication API in different environments under CICS. The connection record is also shown for each one of the environments.

Code Example 4-1 COBOL CICS implementation of a COBOL connection record

---

01 CONNECT-RECORD.

03 CONNECT-OLDAPPLID PIC X(8).

03 CONNECT-VERSION PIC X(2) VALUE '20'.

03 CONNECT-RUNMODE PIC X VALUE '0'.

03 CONNECT-STORAGE PIC S9(8) VALUE +0 COMP.

03 CONNECT-APPLID PIC X(64).

03 CONNECT-DESTNODE PIC X(64).

03 CONNECT-SERVICE PIC X(64).

03 CONNECT-USERID PIC X(16).

03 CONNECT-PASSWORD PIC X(16).

03 CONNECT-APPLREQ PIC X(2).

03 CONNECT-RC PIC X(2).

03 CONNECT-APPLIND PIC X(2).

03 CONNECT-DATATYPE PIC X(1).

03 CONNECT-ACTLEN PIC S9(8) COMP.

03 CONNECT-BUFLEN PIC S9(8) COMP.

03 CONNECT-DATA-BUFFER.

05 CONNECT-DATA PIC X(NNNNN).

* NNNNN = MAX-BUFFSIZE <= 32500.