Developer Products - ObjectQ - UNIX & MVS

...... Return to "Release Notes" page ......

1. INTRODUCTION

This document is largely based on an original authored by Steve Elkind, William Rieth and Brian Meekings.

1.1. Purpose

The purpose of this document is to provide guidelines for applications that desire to establish client-server relationship between Unix and MVS and utilize the ObjectQ middleware product , underlying message transport systems (BEA's DECmessageQ or IBM's MQ Series) and gateway products (Digital's QmsgBridge gateway) as the vehicle for this interface. At the present time, ObjectQ supports those applications that utilize Unix as the client and MVS as the server (Unix initiates all the activity). It has been requested that this interface be expanded to support MVS as the client and Unix as the server. This document provides information on what must be done by an application in order to utilize these products for this type of interfaces.

1.2. Scope

This document describes only the interface between Unix and MVS using the ObjectQ product, message transport systems and QmsgBridge gateway product. It does not provide a description of the full ObjectQ product or discuss the use of the LU6.2 interface. The LU6.2 interface is covered in another document and will not be discussed in any detail here. It will focus on those portions of the ObjectQ product that are concerned with this type of interface only.

1.3. Audience

This document is intended for use by developers of those applications that have a need to get or provide data to legacy MVS applications. In most cases, these interfaces are interim interfaces and will be replaced when an application has fully migrated to the Unix platform.

1.4. Overview

The following diagrams are a pictorial representation of the interface between Unix and MVS.

The diagram shown above illustrates the request and the response when Unix functions as a client and MVS is the server. Under this interface, the application manager invokes ObjectQ methods ( sample code provided below) to transform the ObjectQ message into an IMS transaction message which contains the ObjectQ header. The message is then sent by ObjectQ to the QmsgBridge gateway which in turn takes the message off the DECmessageQ queue and formats it as an MQ Series message (Unix). The process then forwards the message to MQ Series running on MVS. In MVS (via the User written Data Mover), the message is taken off the MQ Series queue and placed on the IMS message queue. The transaction on the IMS queue causes a scheduling of the transaction program based upon the transaction code contained in the IMS transaction header. The program retrieves the requested data and returns the message to the IMS message queue along with the ObjectQ header, which must be preserved. The user's Data Mover then gets the message off the IMS message queue and puts it on the MQ Series queue which in turn forwards the response to QmsgBridge, which forwards it to the Unix user application. The application in turn invokes the ObjectQ methods to convert the transaction format into the ObjectQ format message.

It is important to note that the ObjectQ header must be preserved and an application must handle the translation from ASCII to EBCDIC and the reverse on the return trip. The translation from ASCII to EBCDIC for the message transport header is handled by the message transport system, and for the ObjectQ header does not matter because its contents are unaltered and returned exactly as they appeared in the request. The application Data Mover would be responsible for the translation of the user application data since it would have to be converted before it is inserted.

The above diagram shows the request and the response when MVS functions as a client and Unix is the server. Under this interface, the application manager on the MVS side must place a transaction on the IMS message queue containing the ObjectQ header (more details later on the construction of the ObjectQ header). The message is then extracted from the IMS message queue by the application's Data Mover which would translate the message from EBCDIC to ASCII and place it on the MVS MQ Series queue. The message would then go through the QmsgBridge gateway and be forwarded to the Unix Server Application. The Unix Application would retrieve the necessary data and invoke the appropriate ObjectQ methods to have the message transformed into the transaction format and insert it into a queue on the QmsgBridge gateway. This would return the response to the MVS MQ Series queue. The Data Mover would get the response off the MQ Series queue, translate the message data from ASCII to EBCDIC and place the response on the IMS message queue.

2. INTERFACE DETAILS

2.1. Message Formats

The following are illustrations of how IMS transaction formats appear before the use of ObjectQ and how they appear after ObjectQ is introduced. The representation utilizes COBOL language syntax.

2.1.1. Pre ObjectQ Transaction Formats

The following table illustrates how IMS transactions would appear before ObjectQ is introduced. The first column rould appear to a program associated with the transaction code (the first eight represents how the message would appear on the IMS message queue; the second shows how the message w bytes of the external message identifies which transaction/program must be scheduled); the third column represents the format used to return the message to IMS; the last column shows the message as IMS places in on the IMS message queue.

PRE ObjectQ FORMATS

Input Message From Outside Source

Message as seen by IMS Program

Output from IMS Message Program

Output Message as seen Externally

INPUT-LL PIC S9(4) COMP.

INPUT-LL PIC S9(4) COMP.

INPUT-ZZ PIC S9(4) COMP.

INPUT-ZZ PIC S9(4) COMP

TRANS-CODE PIC X(8).

TRANS-CODE PIC X(8).

TRANS-CODE PIC X(8).

TRANS-CODE PIC X(8).

FILLER PIC X.

FILLER PIC X.

FILLER PIC X.

FILLER PIC X.

iNPUT-USER-DATA.

iNPUT-USER-DATA.

OUTPUT-USER-DATA.

OUTPUT-USER-DATA.

2.1.2. Post ObjectQ Transaction Format

The following illustrates how the IMS message formats after ObjectQ has been introduced. Note the only difference is the inclusion of the ObjectQ header immediately behind the FILLER PIC X after the transaction code (TRANS-CODE).

POST ObjectQ FORMAT

Input Message From ObjectQ

Message as seen by IMS Program

Output from IMS Message Program

Output Message as seen by ObjectQ

INPUT-LL PIC S9(4) COMP.

INPUT-LL PIC S9(4) COMP.

INPUT-ZZ PIC S9(4) COMP

INPUT-ZZ PIC S9(4) COMP

I-TRANS-CODE PIC X(8).

I-TRANS-CODE PIC X(8).

O-TRANS-CODE PIC X(8).

O-TRANS-CODE PIC X(8).

FILLER PIC X.

FILLER PIC X.

FILLER PIC X.

FILLER PIC X.

I-OQ-MSG-TYPE PIC X.

I-OQ-MSG-TYPE PIC X.

O-OQ-MSG-TYPE PIC X.

O-OQ-MSG-TYPE PIC X.

I-OQ-CONF-IND PIC X.

I-OQ-CONF-IND PIC X.

O-OQ-CONF-IND PIC X.

O-OQ-CONF-IND PIC X.

FILLER PIC X.

FILLER PIC X.

FILLER PIC X.

FILLER PIC X.

I-OQ-ERROR-IND PIC XX.

I-OQ-ERROR-IND PIC XX.

O-OQ-ERROR-IND PIC XX.

O-OQ-ERROR-IND PIC XX.

I-OQ-LINK-ID PIC S9(4) COMP.

I-OQ-LINK-ID PIC S9(4) COMP.

O-OQ-LINK-ID PIC S9(4) COMP.

O-OQ-LINK-ID PIC S9(4) COMP.

I-OQ-INVOKE PIC S9(8) COMP.

I-OQ-INVOKE PIC S9(8) COMP.

O-OQ-INVOKE PIC S9(8) COMP.

O-OQ-INVOKE PIC S9(8) COMP.

I-OQ-REPLY-T PIC S9(8) COMP.

I-OQ-REPLY-T PIC S9(8) COMP.

O-OQ-REPLY-T PIC S9(8) COMP.

O-OQ-REPLY-T PIC S9(8) COMP.

I-OQ-ACCESS PIC X(8).

I-OQ-ACCESS PIC X(8).

O-OQ-ACCESS PIC X(8).

O-OQ-ACCESS PIC X(8).

I-OQ-VERSION PIC X.

I-OQ-VERSION PIC X.

O-OQ-VERSION PIC X.

O-OQ-VERSION PIC X.

I-OQ-NUM-HOPS PIC X.

I-OQ-NUM-HOPS PIC X.

O-OQ-NUM-HOPS PIC X.

O-OQ-NUM-HOPS PIC X.

I-OQ-MSG-COUNT PIC S9(4) COMP.

I-OQ-MSG-COUNT PIC S9(4) COMP.

O-OQ-MSG-COUNT PIC S9(4) COMP.

O-OQ-MSG-COUNT PIC S9(4) COMP.

I-OQ-RET-PATH PIC X(16).

I-OQ-RET-PATH PIC X(16).

O-OQ-RET-PATH PIC X(16).

O-OQ-RET-PATH PIC X(16).

FILLER PIC X(4).

FILLER PIC X(4).

FILLER PIC X(4).

FILLER PIC X(4).

INPUT-USER-DATA.

INPUT-USER-DATA.

OUTPUT-USER-DATA.

OUTPUT-USER-DATA.

2.2. ObjectQ Methods to Convert Messages

2.2.1. Unix Client - MVS Server

The following is the sample code for the manager sending a request and receiving a response via ObjectQ.

2.2.1.1. Sending a Request

cpEnvelope* env = new cpEnvelope;

//Create a new Envelope

cpXactReqMessage msg;

//Create the Message #

msg.xactid("TRANCODE");

//Set Transaction Code (8 Bytes) #

List<cpAttribute> alist;

//Create Attribute List

cpAttribute Field1("Domain.MyAttr ");

alist.put(Field1);

msg.attributeList(alist);

//Add Attributes to Message

env->addmessage(msg);

//Add Message to Envelope

// *****Message has been transformed to a Transaction Format***** //

cpTransport* t;

//Get pointer to Transport

t = cpXportMgr->transport(ServiceName);

cpInvId invid;

t->send(ServiceName, env, invid);

//Send Envelope to Service

//*****Message Has Been Sent*****//

# Additional Code to support interface to the IMS transactions

2.2.1.2. Receiving a Response

cpEnvelope* env = new cpEnvelope;

//Create the Envelope

cpXactRespMessage msg;

//Create Message #

cpTransport* t;

//Get pointer to Transport

t = cpXportMgr->transport(ServiceName);

t->receive(cpWAIT, env);

//Wait for response Envelope

env->nextMessage(msg, env->xactId());

//Get first Message from Envelope

//***** Message transformed from Transaction Format to ObjectQ Format*****//

List<cpAttribute> alist;

//Create Attribute List

alist = msg.attributeList();

//Get Attribute List

#Additional Code to support interface to the IMS transactions.

.

2.2.2. MVS Client - Unix Server

The following is the sample code for the agent receiving a request and sending a response via ObjectQ.

2.2.2.1. Receiving a Request

cpEnvelope* env = new cpEnvelope;

//Create the Envelope

cpXactReqMessage msg;

//Create Message #

cpTransport* t;

//Get pointer to Transport

t = cpXportMgr->transport(ServiceName);

t->receive(cpWAIT, env);

//Wait for response Envelope

env->nextMessage(msg, env-xactId());

//Get first Message from Envelope

//***** Message transformed from Transaction Format to ObjectQ Format*****//

List<cpAttribute> alist;

//Create Attribute List

alist = msg.attributeList();

//Get Attribute List

#Additional Code to support interface to the IMS transactions

2.2.2.2. Sending a Response

cpEnvelope* env = new cpEnvelope;

//Create a new Envelope

cpXactRespMessage msg;

//Create Message #

msg.xactid("TRANCODE");

//Set Transaction Code #

List<cpAttribute> alist;

//Create Attribute List

cpAttribute Field1("Domain.MyAttr");

alist.put(Field1);

msg.attibuteList(alist);

//Add Attributes to Message

env->addmessage(msg);

//Add Message to Envelope

// *****Message has been transformed to a Transaction Format***** //

cpTransport* t;

//Get pointer to Transport Object

t = cpXportMgr->transport(ServiceName);

cpInvId invid;

t->send(ServiceName, env, invid);

//Send Envelope to Service

//*****Message Has Been Sent*****//

#Additional Code to support interface to the IMS transactions

2.3. ObjectQ header

The following provides information on the ObjectQ header and how it is populated. The attributes in the ObjectQ header are:

HEADER FIELD

DESCRIPTION

TRANS-CODE PIC X(8).

IMS Transaction Code / the transaction to be scheduled to process this response. Its length is from 1-8 characters with blanks padded to the right.

FILLER PIC X.

This always is a blank.

I-OQ-MSG-TYPE PIC X.

100 for request, 101 for response. ObjectQ needs this field.

I-OQ-CONF-IND PIC X.

Not used in this interface.

FILLER PIC X.

Should be blank.

I-OQ-ERROR-IND PIC XX.

This is used by the communications handler in the LU6.2 gateway solution. It is for use by the application, and thus could conceivably be user-defined. Current settings are 'TA' (transaction abort), 'CF' (communications failure) or 'GE' (general error). ObjectQ does not use this field. Similarly, this could be used to communicate information over the QmsgBridge regarding the status of an IMS transaction.

I-OQ-LINK-ID PIC S9(4) COMP.

Where multiple envelopes constitute a single response, they may be sequenced using this field. This is for application-level use. ObjectQ does not use this field.

I-OQ-INVOKE PIC S9(8) COMP.

This field is used to match responses to requests. The client side is responsible for putting a unique number in this field, and the server side puts the same number back in the response. ObjectQ, where it is used, takes care of this; whichever side does not use ObjectQ is responsible for generating it (client side - we just count up from 1 for successive messages) or preserving it (server side).

I-OQ-REPLY-T PIC S9(8) COMP.

This field contains the 4 byte queue address that the response should come back to. ObjectQ, where it is used, takes care of this. In the case of a single request/response dialogue (rather than a conversation), the client side, if ObjectQ is not used, is responsible for providing this. ObjectQ needs this field.

I-OQ-ACCESS PIC X(8).

User-defined. ObjectQ does not use this field.

I-OQ-VERSION PIC X.

This field is used by ObjectQ to preserve backwards compatibility when internal message structures change. For ObjectQ versions 4.1.5 and beyond, value 5 should be used; for earlier versions 4.x, value 4; for versions 3.x, value 3. ObjectQ needs this field.

I-OQ-NUM-HOPS PIC X.

Where a message (request or response) passes through a number of nodes, this contains the number of hops, and is accumulated as the message traverses its route. For a single hop, this field should be set to 1. ObjectQ, where it is used, takes care of this. ObjectQ needs this field.

I-OQ-MSG-COUNT PIC XX.

Not used for transaction-type messages. ObjectQ does not need this field.

I-OQ-RET-PATH PIC X(16).

For multiple hops, contains the complete return path. For a single hop, this field is empty. ObjectQ, where it is used, takes care of this. ObjectQ needs this field.

FILLER PIC X(4).

2.3.1. Unix Client - MVS Server

When Unix is the Client and MVS is the server, there is no need to worry about the header since it is populated by ObjectQ. The only requirement is that it remain unaltered except for the message type during the interface between Unix and MVS. It should be handled as a piece of flow-through data. Note that the header contains binary fields that will not survive ASCII - EBCDIC - ASCII conversions. Also one should be careful to ensure that data is not converted from small alphabet characters to large alphabet characters accidentally.

2.3.2. MVS Client - Unix Server

When MVS is the client and Unix the server, the header must be populated by the user's application code. It is probably populated by the users Data Mover. The ObjectQ header must be populated by the Data Mover before forwarding it to the QmsgBridge gateway. The description of the fields above provide information what must be present in the header fields. Note that ObjectQ requires the character string fields be in ASCII.

2.4. Data Mover

The responsibility of the user's Data Mover is a program to either get the message off the MVS MQ Series queue and put them on the IMS message queue or to get them off the IMS message queue and put them on the MVS MQ Series queue. Additionally, it should provide convenience functions such as converting from ASCII to EBCDIC, converting from EBCDIC to ASCII and populating the ObjectQ header where necessary. It is envisioned that these functions could be done relatively easily with a BMP (Batch Message Processing) program with a timer pop to wake it up periodically to read either queue. A BMP is suitable for this role because it has accessibility to both queues. In a future release of IMS, a trigger function is planned which would cause scheduling of a MPP (Message Processing Program). The program would then know to get its input from the MVS MQ Series queue rather than the IMS message queue. This capability will probably not be available until IMS 6.1 or later.

2.4.1. Unix Client - MVS Server

In this interface, the Data Mover would be responsible for converting the ObjectQ header and the user's data from ASCII to EBCDIC on the request leg and reconverting the ObjectQ header and user's data from EBCDIC to ASCII on the response leg. It is also responsible for adjusting the ObjectQ message type field. Upon receiving a request message, the Data Mover must extract the ApplIdentityData field from the MQ Series message header; the bridge populates the first nine characters of this field. When sending a response, the data saved from the ApplyIdentityData field must put into the same field in the outgoing message, as the bridge uses this data to correctly forward the response to the client. To allow the use of ApplIdentityData when receiving requests, the queue must be opened with option MQOO_SAVE_ALL_CONTEXT; when sending responses, the queue must be opened with option MQOO_SET_ALL_CONTEXT. There are some additional considerations:

  • The incoming request message will have MQ Series message type MQMT_REQUEST. The outgoing response message must have MQ Series message type MQMT_RESPONSE. It should be sent to the MQ Series queue specified in the ReplyToQ field of the request message. If a response message can not be forwarded to the server's DECmessageQ queue, the message will be returned to the sender by the bridge. In thicase, the MQ Series message type will be MQMT_RTS, which is a user-defined MQ Series message type (in C, "#define MQMT_RTS MQMT_APPL_FIRST +1").
  • The priority and persistence of the response message should normally match those of the request message.

2.4.2. MVS Client - Unix Server

In this interface, the Data Mover would be responsible for populating the ObjectQ header and converting the ObjectQ header and the user's data from EBCDIC to ASCII on the request leg and reconverting the ObjectQ header and user's data from ASCII to EBCDIC on the response leg. When sending a request message via MQ Series and through the message bridge, there are some additional conditions the Data Mover must meet:
  • The MQ Series message type on the outgoing request must be MQMT_REQUEST, which informs the bridge that there will be a reply expected. The MQ Series message type on the incoming reply will be MQMT_REPLY. If a request message can not be forwarded to the server's DECmessageQ queue, the message will be returned to the sender by the bridge. In this case, the MQ Series message type will be MQMT_RTS, which is a user-defined MQ Series message type (in C, "#define MQMT_RTS MQMT_APPL_FIRST +1"). The bridge will map MQ Series priority DefPriority to DECmessageQ priority 0, and MaxPriority to priority 1.

  • The bridge will forward messages sent with MQ Series persistence using DECmessageQ MRS. NOTE: current plans envision separate queues on the bridge for persistent and non-persistent messages for performance reasons, although they can map to the same DECmessageQ queue on the server (there is a symmetric concern for Unix clients and MVS servers). This should be taken into account when designing MVS client applications.

...... Return to "Release Notes" page ......