Chapter 4 . Using the MessageQ MVS Client

This chapter provides the information needed to build an application that can use the MessageQ MVS Client. It covers the following topics:

Architectural Overview

The MessageQ MVS Client, Version 3.2, is a client implementation of the MessageQ Application Programming Interface (API). It relies on a MessageQ server group to provide complete message queuing. If the network connection to the MessageQ server group is lost or unavailable, the MessageQ MVS Client optionally stores messages in a local journal file for later retransmission.

The MessageQ MVS Client provides an object library (DMQ.V3R2.MVSLIB) to support MessageQ enabled applications. In addition, it includes the following JCL procedures:

What Is the Client Library Server?

The Client Library Server (CLS) is a MessageQ application that runs on a MessageQ Server system as a background server to handle multiple MVS Client connections. The CLS performs all communication with the MVS Client library for each client task until the application detaches from the message queuing bus. The message queue operations and network activity of each client are isolated from other clients.

On server systems where both the operating system and MessageQ implementation support multithreading (such as MessageQ on Windows NT), the CLS is multithreaded. On UNIX server systems, the CLS uses a separate process to handle each MVS Client connection. On OpenVMS server systems, the CLS can operate in the following modes:

When the server starts, it initializes a listener process (or thread) that establishes a network endpoint and waits for connections from MVS Clients. The endpoint on which the CLS listens is determined by the command-line arguments used to start the server. MVS Clients attempt to connect to the CLS when they initiate an attach queue operation.

The MVS Client Library uses configuration information in the MessageQ Server group configuration file to identify the location of the CLS. The CLS creates a server subprocess (or server thread with a client context variable) for each new client connection. The server process or thread terminates when the client detaches from the bus, or the network connection is closed.

How Do the MVS Client and CLS Work Together?

The MessageQ MVS Client uses an internal request/response protocol to the CLS running on a MessageQ Server system. The MessageQ MVS Client provides a "lightweight" client connection to the MessageQ message queuing bus.

The implementation is considered lightweight because:

The MVS Client connection to the message queuing bus is provided by a network connection between the MessageQ MVS Client library and a CLS process in the remote MessageQ server group. Figure 4-1 shows the relationship of the MVS Client and CLS to the MessageQ message queuing bus.

Figure 4-1 MessageQ Client and Server Components

The CLS acts as a remote agent to perform MessageQ messaging functions in the MessageQ Server group on behalf of the MVS Client. The MVS Client library establishes a network connection to the CLS when an application initiates an attach queue operation. The connection to the CLS is closed when the application performs a detach queue operation.

How the MVS Client uses MessageQ Function Calls

All MessageQ API functions supported by the MVS Client are processed using the following sequence of events:

  1. The application makes a MessageQ function call to the MVS Client library.

  2. The MVS Client library verifies the function call arguments and sends them in a request to the CLS.

  3. When a request arrives, the CLS makes the corresponding MessageQ function call in the server group.

  4. When the MessageQ function call on the server group completes, the CLS sends the return parameters and function status in a response back to the MVS Client that sent the request.

  5. The MVS Client library waits for the response from the CLS. When the response arrives, the MVS Client library function call returns to the application with the return arguments and function status.

Figure 4-2 shows the communication layers used by a MessageQ MVS Client application.

Figure 4-2 MessageQ MVS Client Library Architecture

The MessageQ MVS Client library allows only one MessageQ function call from the same application to be in progress at a time, with the exceptions of pams_exit and pams_detach_q. For example, if an application calls pams_get_msgw and then calls pams_put_msg before the get message function call returns, the pams_put_msg function returns immediately with an error status value of PAMS__PREVCALLBUSY.

The MessageQ MVS Client library allows multiple applications to connect to queues on the message queuing bus. The library creates a separate network connection to the CLS for each application using MessageQ. The total number of applications that can connect to the message queuing bus is limited by the number of TCP/IP sessions. The Client library uses the Berkeley Socket API for network services.

Store-and-Forward Journaling

The MVS Client provides a SAF journal to store recoverable messages when the connection to CLS is not available. Local SAF journal processing is available when Message Recovery Services (MRS) are enabled in the MVS Client configuration.

When message recovery is enabled, the journal is turned on when the MessageQ MVS Client application first initiates an attach operation. If the CLS is not available at the time of an attach, the operation completes with return a status of PAMS__JOURNAL_ON.

When the communications link to the designated server is down, and MRS is enabled, messages using the following delivery modes are written to a disk journal:

Messages sent with these recoverable delivery modes are written to the SAF file, which uses the VSAM KSDS format. A DD statement for DMQJRNL must be included in the execution JCL and the name must be the same as the one created when configuring the environment. When the communications link to the designated server is restored, all journaled traffic is transmitted, maintaining (FIFO) order for recoverable messages.

When the journal is on, messages sent using a reliable delivery mode are saved to the journal. When the connection to the CLS is reestablished, all messages in the SAF journal are sent before new messages are processed.

Before you can use the MRS configuration option of the MVS Client, you must create the SAF journal. Refer to the configuration instructions in Chapter 3 for information on how to create the SAF journal.

Building Your Application

This topic describes how to build your application to use the MessageQ MVS Client library. Your system must have a program development environment that provides a compiler and linker. Building your application covers the following topics:

MessageQ API Support

The MessageQ MVS Client supports all functions, except pams_get_msga pams_cancel_get, pams_open_jrn, pams_read_jrn, and pams_close_jrn, in the MessageQ application programming interface (API) for the MessageQ Server platforms. To learn about the MessageQ API calls, refer to the Programmer's Guide.

Sample Programs

The MessageQ MVS Client is distributed with a number of sample application programs that demonstrate many of the features of the MessageQ API. If the sample programs were installed during the MVS Client installation, they will be located in the following dataset:

DMQ.V3R2.SRC

C sample programs

DMQ.V3R2.COBLIB

COBOL sample programs

The sample programs consist of C and COBOL language source programs. These samples are identical to the sample programs distributed with the other MessageQ products, and demonstrate the portability of the MessageQ API across all supported platforms.

To run the sample applications, the MessageQ MVS Client configuration for the server hostname and endpoint must be set for your environment. The Client Library Server (CLS) must be running on a MessageQ Server for the sample program to work.

To build a sample program using TCP/IP to communicate with the server, refer to the following sections on linking and running MessageQ applications for the MVS environment.

MVS Client-Specific Return Codes

All MessageQ return codes are defined in the include file, P@RETURN in dataset DMQ.V3R2.INCL for C programs and in the COBOL copy book DMQRC in dataset DMQ.V3R2.COBLIB for COBOL programs. Some return codes are implemented only in the MessageQ MVS Client; others are not implemented in the client.

Table 4-1 lists the return codes specific to the MessageQ MVS Client
Table 4-1 MessageQ MVS Client Specific Return Codes
Return Code Description

PAMS__JOURNAL_FAIL

MRS could not add messages to the local journal because of an operating system I/O error.

PAMS__JOURNAL_FULL

MRS could not add messages to the local journal because it is full.

PAMS__JOURNAL_ON

The link to the CLS is broken and the MRS service successfully wrote the message to the SAF journal. This return code can be treated as a success status.

PAMS__LINK_UP

The link to the CLS has been reestablished. This return code can be treated as a success status.

PAMS__NETERROR

The network connection to the CLS is broken.

PAMS__NETNOLINK

The network connection to the CLS is not available.

PAMS__PREVCALLBUSY

A previous MessageQ function call is still in progress.

Include Files for C and COBOL

The MessageQ MVS Client provides include files for C and COBOL language programs. The include files contain the MessageQ API function prototype declarations, MessageQ return codes, symbolic constants used for API parameters, and additional declarations for using MessageQ message-based services.

Table 4-2 lists the MessageQ MVS Client C language include files. Note that the MVS include file names differ from the C language conventions due to MVS file naming restrictions. When referring to the include file names in your C language programs, use the C language file naming convention. For example, P@ENTRY should be included as p_entry.h.
Table 4-2 C Language Include Files
Include File Contents

P@ENTRY

Function prototypes and type declarations for the MessageQ API

P@RETURN

Return status values

P@SYMBOL

Symbolic constants used for function parameters

P@PROCES

Constant definitions for MessageQ (for OpenVMS) processes

P@GROUP

Constant definitions for MessageQ message-based services

P@TYPECL

Constant definitions of MessageQ message type and class for message-based services

The return codes in P@RETURN define the return codes using the values from the portable MessageQ implementation for UNIX and Windows NT. When the CLS is running on OpenVMS, the return codes from MessageQ for OpenVMS are converted to the equivalent value for the portable MessageQ implementation.

Table 4-3 lists the MessageQ MVS Client COBOL Copy Books
Table 4-3 COBOL Language Include Files
Include File Contents

DMQCLASS

Define MessageQ message classes

DMQGROUP

Define MessageQ sample groups

DMQPCESS

Define MessageQ sample queues

DMQRC

Define MessageQ API return codes

DMQSAMP1

Sample COBOL batch program

ZDMQPROG

Sample Cobol CICS program

Compiling and Linking C Programs

The MessageQ MVS Client contains sample JCL to compile an MVS Client C program. You must include the MessageQ userlib DMQ.V3R2.INCL to the C compiler to resolve the MessageQ include files. Listing 4-1 shows the JCL for compiling MVS batch programs coded in C.

Listing 4-1 Sample JCL for Compiling MVS Batch C Programs 
//COMP   EXEC EDCCLIB,
 
//       INFILE='DMQ.V3R2.SRC(userprog)',
 
//       LIBRARY=`DMQ.USEROBJ',MEMBER=`XGET', 
//   CPARM='LONGNAME,EXPMAC,NOMAR,DEF(MVS,IBM370),SOURCE,RENT'
 
//COMPILE.USERLIB DD DSN=DMQ.V3R2.INCL,DISP=SHR

If your application will run in MVS batch, you must prelink with dataset DMQ.V3R2.MVSLIB specified on the SYSLIB DD statement in the prelink step. Listing 4-2 shows the JCL for linking for MVS batch programs coded in C.

Listing 4-2 Sample JCL for Linking MVS Batch C Programs 
//PLINK  EXEC  EDCPL,
//     INFILE=`DMQ.USEROBJ(userprog)',
//     OUTFILE=`DMQ.V3R2.LINKLIB(XGET),DISP=SHR',
//     PPARM=`NONCAL',
//     LPARM=`LET,AMODE(31),RMODE(ANY),XREF,MAP'
//PLKED.SYSLIB DD  DSN=DMQ.V3R2.MVSLIB,DISP=SHR
//LKED.SYSLIB  DD
//             DD  DSN=TCPIP.V3R1.SEZACMTX,DISP=SHR
//

Compiling and Linking COBOL Programs

To develop MessageQ programs using the COBOL programming language, use the CLAPI programming interface. This interface converts all MessageQ COBOL function calls into the equivalent C function calls documented in the MessageQ Programmer's Guide.

In addition, because it is difficult to define a one byte integer using the COBOL programming language, the following MessageQ arguments must be defined as S9(9)COMP in MessageQ COBOL programs:
API Function Argument name

pams_confirm_msg

field_j

pams_get_msg

priority

pams_get_msgw

priority

pams_put_msg

priority, delivery, and uma

The CLAPI interface adjusts the calling parameters from COBOL prior to making the MessageQ function call. Refer to the sample COBOL programs for example field definitions. Table 4-4 lists the CLAPI function calls and their corresponding MessageQ C program function calls.
Table 4-4 Supported COBOL Function Calls
MessageQ CLAPI Function Call MessageQ C Function Call

CMQATTCH

pams_attach_q

CMQLOCQ

pams_locate_q

CMQDETCH

pams_detach_q

CMQGET

pams_get_msg

CMQGETW

pams_get_msgw

CMQPUT

pams_put_msg

CMQCONF

pams_confirm_msg

CMQSSEL

pams_set_select

CMQCSEL

pams_cancel_select

CMQSTIME

pams_set_timer

CMQCTIME

pams_cancel_timer

CMQPEND

putil_show_pending

CMQILEA

putilea

CMQILAE

putilae

CMQEXIT

pams_exit

MessageQ API arguments are called by reference as shown below: 

CALL 'CMQATTCH'      USING   BY REFERENCE ATTACH-MODE
                             BY REFERENCE REQ-PROCESS-NUM
                             BY REFERENCE Q-TYPE
                             BY REFERENCE Q-NAME
                             BY REFERENCE Q-NAME-LEN
                     RETURNING RETURN-CODE.

VS COBOL II developers must be aware of the following points:

The MVS Client includes sample JCL to compile and link COBOL programs. The file is located in DMQ.V3R2.CNTL as member DMQCOBOL. Contact your Systems Programmer to obtain the COBOL library names used at your site. Listing 4-3 shows the sample JCL to compile and link MessageQ COBOL programs.

Listing 4-3 JCL for Compiling and Linking COBOL Programs 
//DMQCOBOL  JOB  ,DMQ,CLASS=A,MSGCLASS=X
 
//*
 
//*  JCLLIB  ORDER=(IGY.V1R2M0.SIGYPROC)  IBM COBOL FOR MVS PROCLIB
 
//*
 
//*  COMPILE, PRE-LINK, AND LINKEDIT A BATCH DMQ COBOL PROGRAM
 
//*
 
//   EXEC  IGYWCPL,
 
//   PGMLIB='DMQ.V3R2.LINKLIB',
 
//   GOPGM=DMQSAMP1,
 
//   PARM.COBOL='LIB,APOST,OBJECT,MAP,LIST,XREF,NODYNAM,RENT',
 
//   PARM.LKED='AMODE(31),RMODE(ANY),XREF,MAP,LET=12'
 
//*
 
//SYSLIB DD  DSN=DMQ.V3R2.COBLIB,DISP=SHR
 
//SYSIN  DD  DSN=DMQ.V3R2.COBLIB(DMQSAMP1),DISP=SHR
 
//*
 
//PLKED.SYSLIB DD DSN=DMQ.V3R2.MVSLIB,DISP=SHR
 
//SYSIN DD
 
//      DD    *
 
     INCLUDE SYSLIB(CLAPI)              (DMQ COBOL API)
 
     INCLUDE SYSLIB(CLNOCICS)           (RESOLVED CICS ENTRY NAMES)
 
//*
 
//LKED.SYSLIB  DD
 
//             DD DSN=TCPIP.V3R1.SEZACMTX,DISP=SHR  (FOR TCPIP)
 
//

Running Your Application

This topic explains how to run your application including:

To use the MessageQ MVS Client, the following software requirements must be met:

Your MessageQ Server and Client systems must have a network communication link. Have your TCP/IP network administrator verify the network connection to ensure that the systems are properly configured.

For a complete description of MessageQ Server systems and TCP/IP transports supported by the MessageQ MVS Client, see the MessageQ MVS Client, Version 3.2 Software Product Description (SPD) or the Release Notes.

Run-time Files

To execute a MessageQ MVS messaging application, the MessageQ initialization file must be created and the DMQINI DD card pointing to the dataset must be in the execution JCL.

Byte Order

MessageQ provides the capability to send and receive messages between many different types of operating systems and CPU architectures. The byte order used by different CPU architectures is referred to as either little endian (or right-to-left order) or big endian (left-to-right). Application designers must take into account the differences in byte ordering when designing a distributed application with MessageQ. IBM MVS systems use network byte order (big endian).

The byte order used on the MessageQ MVS Client system and the CLS platform might be different. For example, a Digital Alpha system is a little endian machine and an HP PA-RISC system is a big endian machine. This means that integer values sent in the message area from the client are represented differently when received by the application server on the host.

The MessageQ MVS Client and CLS handle differences in byte ordering by using network byte order when the client and server system are based on different representations (network byte order is big endian). This ensures that the arguments to the MessageQ API functions called on the client are passed correctly to the CLS platform to initiate the messaging operation. However, the MessageQ MVS Client does not perform byte-swapping on the user data passed in the message area for pams_put_msg or pams_get_msg calls.

There are alternative techniques for handling the byte order differences in the client or server application components:

For UNIX applications, the data marshaling routines can be implemented as a set of library routines designed specifically to support data format conversion. These routines are typically written such that each marshaling routine performs one specific record conversion.

The Socket API provides routines to support byte-order conversion. These routines are htonl, htons, ntohl, and ntohs. For example, htonl means host to network long (32-bit) conversion. Marshaling routines can call these functions by including the file socket.h, and linking with the socket library.

ASCII to EBCDIC Translation

The IBM MVS environment uses the EBCDIC file format. All platforms that support MessageQ message servers use the ASCII file format. The MessageQ MVS Client includes two functions for translating character data as follows:

This section provides reference information that describes how to use both functions.

putilae

Translates character strings from ASCII to EBCDIC format. This function call is available on MVS systems only.

Syntax

int32 putilae (string, length)

Arguments
Argument Data Type Mechanism Prototype Access

string

char

reference

char *

passed/
returned

length

short

reference

short *

passed

Argument Definitions
string

Specifies the character string which is to be converted from ASCII to EBCDIC.

length

Specifies the length of the string to convert.

Description

The putilae function accepts the string to be translated using the string argument and returns the translated string using the same argument.

Return Values
Return Code Platform Description

PAMS__FAILED

MVS

Unable to convert string

PAMS__SUCCESS

MVS

Normal successful completion

putilea

Translates character strings from EDCDIC to ASCII. This function call is available only on MVS systems.

Syntax

int32 putilea (string, length)

Arguments
Argument Data Type Mechanism Prototype Access

string

char

reference

char *

passed/
returned

length

short

reference

short *

passed

Argument Definitions
string

Specifies the character string which is to be converted from EBCDIC to ASCII.

length

Specifies the length of the string to convert.

Description

The putilea function accepts the string to be translated using the string argument and returns the translated string using the same argument.

Return Values
Return Code Platform Description

PAMS__FAILED

MVS

Unable to convert string

PAMS__SUCCESS

MVS

Normal successful completion

Running MessageQ Applications under CICS

This section describes how to configure your environment to run MessageQ applications under IBM CICS by:

Defining FCT Entries

To run MessageQ applications in the MVS CICS environment, you must define FCT entires as shown in Listing 4-6.

Listing 4-6 FCT Entries to Define for CICS Environment 
DEFINE FILE(DMQINI) GROUP(DMQFILES)
  DSNAME(DMQ.V3R2.INI) LSRPOOL(1)
  DSNSHARING(ALLREQS) STRINGS(1)
  STATUS(ENABLED) OPENTIME(FIRSTREF) DISPOSITION(SHARE)
  DATABUFFERS(2) INDEXBUFFERS(1) RECORDFORMAT(V)
  ADD(YES) BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES) 

DEFINE FILE(DMQELOG) GROUP(DMQFILES)
   DSNAME(DMQ.V3R2.ERR) LSRPOOLID(1)
   DSNSHARING(ALLREQS) STRINGS(1)
   STATUS(ENABLED) OPENTIME(FIRSTREF) DISPOSITION(SHARE)
   DATABUFFERS(2) INDEXBUFFERS(1) RECORDFORMAT(V)
   ADD(YES) BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)

DEFINE FILE(DMQLOG) GROUP(DMQFILES)
  DSNAME(DMQ.V3R2.LOG) LSRPOOL(1)
  DSNSHARING(ALLREQS) STRINGS(1)
  STATUS(ENABLED) OPENTIME(FIRSTREF) DISPOSITION(SHARE)
  DATABUFFERS(2) INDEXBUFFERS(1) RECORDFORMAT(V)
  ADD(YES) BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)

DEFINE FILE(DMQSAF) GROUP(DMQFILES)
  DSNAME(DMQ.V3R2.SAF) LSRPOOL(1)
  DSNSHARING(ALLREQS) STRINGS(1)
  STATUS(ENABLED) OPENTIME(FIRSTREF) DISPOSITION(SHARE)
  DATABUFFERS(2) INDEXBUFFERS(1) RECORDFORMAT(V)
  ADD(YES) BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)

Defining PCT entries

To run MessageQ applications in the MVS CICS environment, you must define the PCT entries to define the CICS transaction code and the CICS MessageQ program to CICS as shown in Listing 4-7.

Listing 4-7 PCT Entries to Define for CICS Environment 
DEFINE PROGRAM(XGET) GROUP(DMQ)
  LANGUAGE(LE370) RELOAD(YES)
 
DEFINE TRANSACTION(XDMQ) GROUP(DMQ)
  PROGRAM(XDMQPROG) TWASIZE(1024) PROFILE(DFHCICST)
  TASKDATALOC(ANY)

Using Message Tracing Under CICS

If the trace options SENTCICSMESSAGES or RECEIVEDCICSMESSAGES are selected in the DMQ initialization file, messages are written to the transient data queue named DMQTLOG. The messages in this queue can be viewed using the CICS transaction CEBR. All records written to this queue are prefixed with the terminal ID, transaction code, date, and time.

Linkediting C Programs for CICS

The MessageQ MVS Client contains a JCL sample for linkediting C Programs in the CICS environment as shown in Listing 4-8.

Listing 4-8 Sample Linkedit JCL for CICS C Programs 
//DMQCICS JOB ,DMQ,CLASS=A, 
//             MSGCLASS=X,MSGLEVEL=(1,1), 
//             TIME=(5,00) 
//*********************************************************
//PLINK   EXEC EDCPL, 
//       INFILE='DMQ.USEROBJ(XGET)', 
//       OUTFILE='SYS2.USERLINK(XDMQPROG),DISP=(SHR,KEEP)', 
//       PLIB='DSN=DMQ.V3R2.MVSLIB,DISP=SHR', 
//       PPARM='NONCAL', 
//       LPARM='LET,AMODE(31),RMODE(ANY),XREF,LIST'     
//LKED.SYSLIB  DD                                   
//             DD DSN=TCPIP.V3R1.SEZATCP,DISP=SHR   
//             DD DSN=TCPIP.V3R1.SEZACMTX,DISP=SHR    
//             DD DSN=CICS410.SDFHLOAD,DISP=SHR  
//LKED.SYSIN DD *                                 
 INCLUDE SYSLIB(DFHELII)   REQUIRED BY CICS        
 INCLUDE SYSLIB(EZACIC07)  REQUIRED BY CICS       
//