|
|
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:
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.
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. |
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.
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.
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.
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:
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:
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/ |
length |
short |
reference |
short * |
passed |
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 |
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/ |
length |
short |
reference |
short * |
passed |
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 |
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|