Building Your Application

 

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

• BEA MessageQ API Support

• Sample Programs

• MVS Client-specific Return Codes

• Include Files for C and COBOL

• Compiling and Linking C Programs

• Compiling and Linking COBOL Programs

• Byte Order

• ASCII to EBCDIC Translation

BEA MessageQ API Support

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

Sample Programs

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

DMQ.V5R0.X	C sample programs
DMQ.V5R0.COB	COBOL sample programs and Copy Books

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

To run the sample applications, you must define the server hostname and endpoint for your environment in the BEA MessageQ MVS Client configuration file. The Client Library Server (CLS) must be running on a BEA 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 BEA MessageQ applications for the MVS environment.

MVS Client-specific Return Codes

All BEA MessageQ return codes are defined as follows.

Return codes for . . .	Are defined in . . .
C programs	P@RETURN (an include file) in dataset DMQ.V5R0.H
COBOL programs	DMQRC (a COBOL Copy Book) in dataset DMQ.V5R0.COB

Some return codes are implemented only in the BEA MessageQ MVS Client; others are not implemented in the client.

Table 3-1 lists the return codes specific to the BEA MessageQ MVS Client.

Table 3-1 BEA 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 BEA MessageQ function call is still in progress.

Include Files for C and COBOL

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

Table 3-2 lists the C language include files provided with the BEA MessageQ MVS Client. Note that the names of the MVS include files do not conform to the C language naming conventions due to MVS file naming restrictions. When referring to the include files in your C programs, use the C language file naming convention. For example, P@ENTRY should be included as p_entry.h.

Table 3-2 C Language Include Files

Include File	Contents
P@ENTRY	Function prototypes and type declarations for the BEA MessageQ API
P@RETURN	Return status values
P@SYMBOL	Symbolic constants used for function parameters
P@PROCES	Constant definitions for BEA MessageQ (for OpenVMS) processes
P@GROUP	Constant definitions for BEA MessageQ message-based services
P@MSG	PAMS message API structure definitions
P@STATUS	PAMS status message text translations
P@TYPECL	Constant definitions of BEA MessageQ message type and class for message-based services

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

Table 3-3 lists the BEA MessageQ MVS Client COBOL Copy Books and sample programs.

Table 3-3 COBOL Language Copy Books and Sample Programs

Copy Book	Contents
DMQCLASS	Definition of BEA MessageQ message classes
DMQGROUP	Definition of BEA MessageQ sample groups
DMQPCESS	Definition of BEA MessageQ sample queues
DMQRC	Definition of BEA MessageQ API return codes
DMQSAMP1	Sample COBOL batch program
ZDMQPROG	Sample COBOL CICS program

Compiling and Linking C Programs

The BEA MessageQ MVS Client contains a sample JCL to compile an MVS Client C program. To resolve the BEA MessageQ include files, you must specify the BEA MessageQ library DMQ.V5R0.H to the C compiler. Listing 3-1 shows the JCL for compiling MVS batch programs coded in C.

Listing 3-1 Sample JCL for Compiling MVS Batch C Programs

---

//COMP   EXEC EDCCLIB,
//       INFILE='DMQ.V5R0.X(userprog)',
//       LIBRARY=`DMQ.USEROBJ',MEMBER=`X@GET', 
//   CPARM='LONGNAME,EXPMAC,NOMAR,DEF(MVS,IBM370),SOURCE,RENT'
//COMPILE.USERLIB DD DSN=DMQ.V5R0.H,DISP=SHR

---

If your application is going to be run in MVS batch, you must prelink with dataset DMQ.V5R0.LIB (specified in the SYSLIB DD statement in the prelink step). Listing 3-2 shows the JCL for linking for MVS batch programs coded in C.

Listing 3-2 Sample JCL for Linking MVS Batch C Programs

---

//*
//PLKED  EXEC EDCPL,
//   PPARM='MAP,NONCAL',
//   LPARM='LET,AMODE(31),RMODE(ANY),XREF,MAP',
//   INFILE=DMQ.V5R0.LIB(X@BASIC)',
//   OUTFILE='MQUSER.EXE(X@BASIC),DISP=SHR'
//PLKED.SYSLIB DD DSN=DMQ.V5R0.LIB,DISP=SHR
//SYSIN2  DD  *
   INCLUDE SYSLIB(CLNOCICS)
//LKED.SYSLIB  DD DSN=CEE.SCEELKED,DISP=SHR
//        DD   DSN=TCPIP.SEZACMTX,DISP=SHR
//        DD   DSN=TCPIP.SEZATCP,DISP=SHR
//*

---

Compiling and Linking COBOL Programs

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

In addition, because it is difficult to define a 1-byte integer using COBOL, the following BEA MessageQ arguments must be defined as S9(9)COMP in BEA MessageQ COBOL programs.

API Function	Argument name
pams_confirm_msg	force_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 before making the BEA MessageQ function call. Refer to the sample COBOL programs for example field definitions. Table 3-4 lists the CLAPI function calls and their corresponding BEA MessageQ C program function calls.

Table 3-4 Supported COBOL Function Calls

BEA MessageQ CLAPI Function Call	BEA MessageQ C Function Call
CMQATTCH	pams_attach_q
CMQBIND	pams_bind_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
CMQSTSXT	pams_status_text
CMQEXIT	pams_exit

BEA MessageQ API arguments are called by reference, as follows:

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.

COBOL developers must be aware of the following points:

• All BEA MessageQ COBOL function calls are prefixed with DMQ instead of CMQ.

• You cannot use the RETURNING option of the CALL statement. The PAMS return code is stored in the COBOL reserved field, RETURN_CODE.

• You must check the API function status in RETURN_CODE to verify the result of your request.

• A sample COBOL program is located in DMQ.V5R0.COB.

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

Listing 3-3 JCL for Compiling and Linking COBOL Programs

---

//*
//   EXEC  IGYWCPL,
//   PGMLIB='MQUSER.EXE',
//   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.V5R0.COB,DISP=SHR
//SYSIN  DD  DSN=DMQ.V5R0.COB(DMQSAMP1),DISP=SHR
//PLKED.SYSMSGS DD DSN=CEE.SCEEMSGP(EDCPMSGE),DISP=SHR
//PLKED.STEPLIB DD DSN=SYS1.SCEERUN,DISP=SHR
//PLKED.SYSLIB DD DSN=DMQ.V5R0.LIB,DISP=SHR
//SYSIN DD
//    DD  *
     INCLUDE SYSLIB(CLNOCICS)
//LKED.SYSLIB  DD DSN=CEE.SCEELKED,DISP=SHR
//        DD   DSN=TCPIP.SEZACMTX,DISP=SHR
//        DD   DSN=TCPIP.SEZATCP,DISP=SHR
//*

---

Byte Order

BEA MessageQ provides the capability to send and receive messages among 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 BEA MessageQ. IBM MVS systems use network byte order (big endian).

The byte order used on the BEA 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 BEA MessageQ MVS Client and CLS handle differences in byte ordering by using network byte order when the client and server systems are based on different representations (network byte order is big endian). This ensures that the arguments to the BEA MessageQ API functions called on the client are passed correctly to the CLS platform to initiate the messaging operation. However, the BEA 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.

Two alternative techniques are available for handling byte order differences in the client and server application components:

• You can send user data messages containing only character string data. Integer values are converted to the corresponding character representation before they are sent in a message.

• You can design an application-specific interface for sending and receiving messages that implements marshaling routines for the user data in each message.

For UNIX applications, 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 character encoding scheme. All platforms that support BEA MessageQ message servers use the ASCII character encoding scheme. The BEA MessageQ MVS Client provides two functions, putilae and putilea, for translating character data from ASCII to EBCDIC, and from EBCDIC to ASCII, respectively.

This section provides reference information for the putilae and putilea 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 that is to be converted from ASCII to EBCDIC.

length

Specifies the length of the string to be converted.

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 EBCDIC to ASCII format. This function call is available on MVS systems only.

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 that is to be converted from EBCDIC to ASCII.

length

Specifies the length of the string to be converted.

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