public.dhe.ibm.com · pl/i declaration ...........106 system/390 assembler declaration .....107 tal...

MQSeries®

Application Programming Reference

SC33-1673-06

IBM

NoteBefore using this information and the product it supports, be sure to read the general information under “Appendix I.Notices” on page 689.

Seventh edition (March 2000)

This edition applies to the following products:v MQSeries for AIX® Version 5.1v MQSeries for AS/400® Version 5 Release 1v MQSeries for AT&T GIS UNIX Version 2 Release 2v MQSeries for Digital OpenVMS Version 2 Release 2v MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX) Version 2 Release 2.1v MQSeries for HP-UX V5.1v MQSeries for OS/2® Warp Version 5.1v MQSeries for OS/390® Version 2 Release 1v MQSeries for SINIX and DC/OSx Version 2 Release 2v MQSeries for Sun Solaris V5.1v MQSeries for Tandem NonStop Kernel Version 2 Release 2.0.1v MQSeries for VSE/ESA™ Version 2 Release 1v MQSeries for Windows NT® Version 5.1v MQSeries for Windows® Version 2 Release 0v MQSeries for Windows Version 2 Release 1and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 1994, 2000. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Tables . . . . . . . . . . . . . . . xi

About this book . . . . . . . . . . xiiiWho this book is for . . . . . . . . . . . xiiiWhat you need to know to understand this book xiiiHow to use this book . . . . . . . . . . . xiv

Appearance of text in this book . . . . . . xivTerms used in this book . . . . . . . . . xivLanguage compilers . . . . . . . . . . xv

Summary of changes . . . . . . . . xixChanges for this edition (SC33-1673-06) . . . . . xixChanges for the previous edition included: . . . xixChanges for the fifth edition included: . . . . . xix

Part 1. Data type descriptions . . . . 1

Chapter 1. Elementary data types . . . . 5Conventions used in the descriptions of data types . 5Elementary data types . . . . . . . . . . . 5

MQBYTE - Byte . . . . . . . . . . . . 5MQBYTEn - String of n bytes . . . . . . . . 5MQCHAR - character . . . . . . . . . . 6MQCHARn - String of n characters . . . . . . 6MQHCONN - Connection handle . . . . . . 6MQHOBJ - Object handle . . . . . . . . . 6MQLONG - Long integer . . . . . . . . . 7Elementary data types - C programming language 7Elementary data types - COBOL programminglanguage. . . . . . . . . . . . . . . 8Elementary data types - PL/I language (AIX,OS/2, OS/390, VSE/ESA, and Windows NT only) . 8Elementary data types - System/390 Assembler(OS/390 only) . . . . . . . . . . . . . 9Elementary data types - TAL programminglanguage (Tandem NonStop Kernel only) . . . 10Elementary data types - Visual Basic (Windows3.1, Windows 95, Windows 98, and Windows NT) 10

Chapter 2. Structure data types –programming considerations . . . . . 13Conventions used in the descriptions of data types 13Language considerations . . . . . . . . . . 14

Using the data types in the C programminglanguage . . . . . . . . . . . . . . 14Using the data types in the COBOLprogramming language . . . . . . . . . 17Using the data types in the PL/I programminglanguage . . . . . . . . . . . . . . 20Using the data types in the System/390Assembler programming language . . . . . 22Using the data types in the Visual Basicprogramming language . . . . . . . . . 24

Structure data types . . . . . . . . . . . 25

Chapter 3. MQBO - Begin options . . . 27Overview . . . . . . . . . . . . . . . 27Fields . . . . . . . . . . . . . . . . 27Initial values and language declarations . . . . . 28

C declaration . . . . . . . . . . . . . 28COBOL declaration . . . . . . . . . . . 28PL/I declaration . . . . . . . . . . . . 28Visual Basic declaration . . . . . . . . . 28

Chapter 4. MQCIH - CICS bridge header 29Overview . . . . . . . . . . . . . . . 30Fields . . . . . . . . . . . . . . . . 31Initial values and language declarations . . . . . 41

C declaration . . . . . . . . . . . . . 42COBOL declaration . . . . . . . . . . . 42PL/I declaration . . . . . . . . . . . . 44System/390 assembler declaration . . . . . . 44

Chapter 5. MQCNO - Connect options 47Overview . . . . . . . . . . . . . . . 47Fields . . . . . . . . . . . . . . . . 47Initial values and language declarations . . . . . 52


Chapter 6. MQDH - Distribution header 55Overview . . . . . . . . . . . . . . . 55Fields . . . . . . . . . . . . . . . . 56Initial values and language declarations . . . . . 59


Chapter 7. MQDLH - Dead-letter header 63Overview . . . . . . . . . . . . . . . 63Fields . . . . . . . . . . . . . . . . 65Initial values and language declarations . . . . . 69

C declaration . . . . . . . . . . . . . 70COBOL declaration . . . . . . . . . . . 70PL/I declaration . . . . . . . . . . . . 71System/390 assembler declaration . . . . . . 71TAL declaration . . . . . . . . . . . . 72Visual Basic declaration . . . . . . . . . 72

Chapter 8. MQGMO - Get-messageoptions . . . . . . . . . . . . . . 73Overview . . . . . . . . . . . . . . . 73Fields . . . . . . . . . . . . . . . . 73Initial values and language declarations . . . . 105

C declaration . . . . . . . . . . . . 105COBOL declaration . . . . . . . . . . 106

© Copyright IBM Corp. 1994, 2000 iii

||

PL/I declaration . . . . . . . . . . . 106System/390 assembler declaration . . . . . 107TAL declaration . . . . . . . . . . . 107Visual Basic declaration . . . . . . . . . 108

Chapter 9. MQIIH - IMS bridge header 109Overview. . . . . . . . . . . . . . . 109Fields . . . . . . . . . . . . . . . . 110Initial values and language declarations . . . . 113

C declaration . . . . . . . . . . . . 114COBOL declaration . . . . . . . . . . 114PL/I declaration . . . . . . . . . . . 115System/390 assembler declaration . . . . . 115

Chapter 10. MQMD - Messagedescriptor . . . . . . . . . . . . . 117Overview. . . . . . . . . . . . . . . 118Fields . . . . . . . . . . . . . . . . 119Initial values and language declarations . . . . 170

C declaration . . . . . . . . . . . . 171COBOL declaration . . . . . . . . . . 172PL/I declaration . . . . . . . . . . . 173System/390 assembler declaration . . . . . 173TAL declaration . . . . . . . . . . . 174Visual Basic declaration . . . . . . . . . 175

Chapter 11. MQMDE - Messagedescriptor extension . . . . . . . . 177Overview. . . . . . . . . . . . . . . 177Fields . . . . . . . . . . . . . . . . 179Initial values and language declarations . . . . 182

C declaration . . . . . . . . . . . . 182COBOL declaration . . . . . . . . . . 182PL/I declaration . . . . . . . . . . . 183System/390 assembler declaration . . . . . 183Visual Basic declaration . . . . . . . . . 184

Chapter 12. MQOD - Object descriptor 185Overview. . . . . . . . . . . . . . . 185Fields . . . . . . . . . . . . . . . . 186Initial values and language declarations . . . . 195


Chapter 13. MQOR - Object record 199Overview. . . . . . . . . . . . . . . 199Fields . . . . . . . . . . . . . . . . 199Initial values and language declarations . . . . 200

C declaration . . . . . . . . . . . . 200COBOL declaration . . . . . . . . . . 200PL/I declaration . . . . . . . . . . . 200Visual Basic declaration . . . . . . . . . 200

Chapter 14. MQPMO - Put messageoptions . . . . . . . . . . . . . . 201

Overview. . . . . . . . . . . . . . . 201Fields . . . . . . . . . . . . . . . . 202Initial values and language declarations . . . . 218


Chapter 15. MQPMR - Put-messagerecord . . . . . . . . . . . . . . 223Overview. . . . . . . . . . . . . . . 223Fields . . . . . . . . . . . . . . . . 223Initial values and language declarations . . . . 225


Chapter 16. MQRMH - Messagereference header . . . . . . . . . . 227Overview. . . . . . . . . . . . . . . 227Fields . . . . . . . . . . . . . . . . 228Initial values and language declarations . . . . 234


Chapter 17. MQRR - Response record 239Overview. . . . . . . . . . . . . . . 239Fields . . . . . . . . . . . . . . . . 239Initial values and language declarations . . . . 240


Chapter 18. MQTM - Trigger message 241Overview. . . . . . . . . . . . . . . 241Fields . . . . . . . . . . . . . . . . 243Initial values and language declarations . . . . 246


Chapter 19. MQTMC2 - Triggermessage 2 (character format) . . . . 249Overview. . . . . . . . . . . . . . . 249Fields . . . . . . . . . . . . . . . . 250Initial values and language declarations . . . . 251

C declaration . . . . . . . . . . . . 251COBOL declaration . . . . . . . . . . 252PL/I declaration . . . . . . . . . . . 252

iv MQSeries Application Programming Reference

System/390 assembler declaration . . . . . 252TAL declaration . . . . . . . . . . . 252Visual Basic declaration . . . . . . . . . 253

Chapter 20. MQWIH - Workinformation header . . . . . . . . . 255Overview. . . . . . . . . . . . . . . 255Fields . . . . . . . . . . . . . . . . 255Initial values and language declarations . . . . 257


Chapter 21. MQXP - Exit parameterblock (OS/390 only) . . . . . . . . . 261Overview. . . . . . . . . . . . . . . 261Fields . . . . . . . . . . . . . . . . 261Language declarations . . . . . . . . . . 264


Chapter 22. MQXQH - Transmissionqueue header . . . . . . . . . . . 267Overview. . . . . . . . . . . . . . . 267Fields . . . . . . . . . . . . . . . . 270Initial values and language declarations . . . . 271


Part 2. Function calls . . . . . . . 275

Chapter 23. Call descriptions . . . . 277Conventions used in the call descriptions . . . . 277Using the calls in the C language. . . . . . . 279

Declaring the Buffer parameter . . . . . . 279

Chapter 24. MQBACK - Back outchanges . . . . . . . . . . . . . 281Syntax. . . . . . . . . . . . . . . . 281Parameters . . . . . . . . . . . . . . 281Usage notes . . . . . . . . . . . . . . 282Language invocations . . . . . . . . . . 284

C invocation. . . . . . . . . . . . . 284COBOL invocation . . . . . . . . . . 284PL/I invocation (AIX, OS/2, OS/390, WindowsNT) . . . . . . . . . . . . . . . 284System/390 assembler invocation (OS/390 only) 285TAL invocation (Tandem NSK only) . . . . . 285Visual Basic invocation (Windows only) . . . 285

Chapter 25. MQBEGIN - Begin unit ofwork . . . . . . . . . . . . . . . 287Syntax. . . . . . . . . . . . . . . . 287Parameters . . . . . . . . . . . . . . 287Usage notes . . . . . . . . . . . . . . 288Language invocations . . . . . . . . . . 290

C invocation. . . . . . . . . . . . . 290COBOL invocation . . . . . . . . . . 290PL/I invocation (AIX, OS/2, Windows NT) . . 290Visual Basic invocation (Windows only) . . . 290

Chapter 26. MQCLOSE - Close object 291Syntax. . . . . . . . . . . . . . . . 291Parameters . . . . . . . . . . . . . . 291Usage notes . . . . . . . . . . . . . . 294Language invocations . . . . . . . . . . 296

C invocation. . . . . . . . . . . . . 296COBOL invocation . . . . . . . . . . 296PL/I invocation (AIX, OS/2, OS/390, VSE/ESA,Windows NT . . . . . . . . . . . . 296System/390 assembler invocation (OS/390 only) 297TAL invocation (Tandem NSK only) . . . . . 297Visual Basic invocation (Windows only) . . . 297

Chapter 27. MQCMIT - Commitchanges . . . . . . . . . . . . . 299Syntax. . . . . . . . . . . . . . . . 299Parameters . . . . . . . . . . . . . . 299Usage notes . . . . . . . . . . . . . . 300Language invocations . . . . . . . . . . 302

C invocation. . . . . . . . . . . . . 302COBOL invocation . . . . . . . . . . 302PL/I invocation (AIX, OS/2, OS/390, WindowsNT) . . . . . . . . . . . . . . . 303System/390 assembler invocation (OS/390 only) 303TAL invocation (Tandem NSK only) . . . . . 303Visual Basic invocation (Windows only) . . . 303

Chapter 28. MQCONN - Connectqueue manager . . . . . . . . . . 305Syntax. . . . . . . . . . . . . . . . 305Parameters . . . . . . . . . . . . . . 305Usage notes . . . . . . . . . . . . . . 309Language invocations . . . . . . . . . . 311

C invocation. . . . . . . . . . . . . 311COBOL invocation. . . . . . . . . . . 311PL/I invocation (AIX, OS/2, OS/390, VSE/ESA,Windows NT . . . . . . . . . . . . 311System/390 assembler invocation (OS/390 only) 311TAL invocation (Tandem NSK only) . . . . . 311Visual Basic invocation (Windows only) . . . 312

Chapter 29. MQCONNX - Connectqueue manager (extended) . . . . . 313Syntax. . . . . . . . . . . . . . . . 313Parameters . . . . . . . . . . . . . . 313Language invocations . . . . . . . . . . 314

C invocation. . . . . . . . . . . . . 314COBOL invocation . . . . . . . . . . 314

Contents v

PL/I invocation (AIX, OS/2, Windows NT) . . 314Visual Basic invocation (Windows only) . . . 315

Chapter 30. MQDISC - Disconnectqueue manager . . . . . . . . . . 317Syntax. . . . . . . . . . . . . . . . 317Parameters . . . . . . . . . . . . . . 317Usage notes . . . . . . . . . . . . . . 318Language invocations . . . . . . . . . . 319

C invocation. . . . . . . . . . . . . 319COBOL invocation . . . . . . . . . . 319PL/I invocation (AIX, OS/2, OS/390, VSE/ESA,Windows NT) . . . . . . . . . . . . 319System/390 assembler invocation (OS/390 only) 319TAL invocation (Tandem NSK only) . . . . . 319Visual Basic invocation (Windows only) . . . 320

Chapter 31. MQGET - Get message 321Syntax. . . . . . . . . . . . . . . . 321Parameters . . . . . . . . . . . . . . 321Usage notes . . . . . . . . . . . . . . 326Language invocations . . . . . . . . . . 330


Chapter 32. MQINQ - Inquire aboutobject attributes . . . . . . . . . . 333Syntax. . . . . . . . . . . . . . . . 333Parameters . . . . . . . . . . . . . . 333Usage notes . . . . . . . . . . . . . . 344Language invocations . . . . . . . . . . 345


Chapter 33. MQOPEN - Open object 347Syntax. . . . . . . . . . . . . . . . 347Parameters . . . . . . . . . . . . . . 347Usage notes . . . . . . . . . . . . . . 357Language invocations . . . . . . . . . . 362


Chapter 34. MQPUT - Put message 365Syntax. . . . . . . . . . . . . . . . 365

Parameters . . . . . . . . . . . . . . 365Usage notes . . . . . . . . . . . . . . 370Language invocations . . . . . . . . . . 374


Chapter 35. MQPUT1 - Put onemessage . . . . . . . . . . . . . 377Syntax. . . . . . . . . . . . . . . . 377Parameters . . . . . . . . . . . . . . 377Usage notes . . . . . . . . . . . . . . 382Language invocations . . . . . . . . . . 383


Chapter 36. MQSET - Set objectattributes . . . . . . . . . . . . . 387Syntax. . . . . . . . . . . . . . . . 387Parameters . . . . . . . . . . . . . . 387Usage notes . . . . . . . . . . . . . . 391Language invocations . . . . . . . . . . 391


Chapter 37. MQSYNC - Synchronizestatistics updates (Tandem NSK only) . 395Syntax. . . . . . . . . . . . . . . . 395Parameters . . . . . . . . . . . . . . 395Language invocations . . . . . . . . . . 396

C language invocation . . . . . . . . . 396COBOL language invocation . . . . . . . 396TAL language invocation . . . . . . . . 396

Part 3. Attributes of objects . . . . 397

Chapter 38. Attributes of MQSeriesobjects . . . . . . . . . . . . . . 399

Chapter 39. Attributes for all queues 401

Chapter 40. Attributes for localqueues and model queues . . . . . . 407

vi MQSeries Application Programming Reference

Chapter 41. Attributes for localdefinitions of remote queues . . . . . 425

Chapter 42. Attributes for aliasqueues . . . . . . . . . . . . . . 427

Chapter 43. Attributes for namelists 429

Chapter 44. Attributes for processdefinitions . . . . . . . . . . . . . 431

Chapter 45. Attributes for the queuemanager . . . . . . . . . . . . . 435

Part 4. Appendixes . . . . . . . . 451

Appendix A. Return codes . . . . . . 453Completion codes . . . . . . . . . . . . 453Reason codes . . . . . . . . . . . . . 453

Appendix B. MQSeries constants . . . 535List of constants . . . . . . . . . . . . 535

MQ_* (Lengths of character string and bytefields) . . . . . . . . . . . . . . . 535MQACT_* (Accounting token). . . . . . . 536MQACT_* (Action option) . . . . . . . . 537MQACTT_* (Accounting token type) . . . . 537MQAT_* (Application type) . . . . . . . 537MQBND_* (Binding) . . . . . . . . . . 538MQBO_* (Begin options) . . . . . . . . 538MQBO_* (Begin options structure identifier) . . 538MQBO_* (Begin options version) . . . . . . 538MQBT_* (Bridge type) . . . . . . . . . 538MQCA_* (Character attribute selector) . . . . 538MQCACF_* (Character attribute commandformat parameter) . . . . . . . . . . . 539MQCACH_* (Channel character attributecommand format parameter) . . . . . . . 540MQCADSD_* (CICS header ADS descriptor) 541MQCC_* (Completion code) . . . . . . . 541MQCCSI_* (Coded character set identifier) . . 541MQCCT_* (CICS header conversational task) 541MQCD_* (Channel definition structure length) 541MQCD_* (Channel definition structure version) 542MQCDC_* (Channel data conversion) . . . . 542MQCF_* (Channel capability flags) . . . . . 542MQCFAC_* (CICS header facility) . . . . . 542MQCFC_* (Command format control options) 542MQCFH_* (Command format header structurelength) . . . . . . . . . . . . . . 542MQCFH_* (Command format header version) 543MQCFIL_* (Command format integer-listparameter structure length). . . . . . . . 543MQCFIN_* (Command format integerparameter structure length). . . . . . . . 543MQCFSL_* (Command format string-listparameter structure length). . . . . . . . 543

MQCFST_* (Command format string parameterstructure length) . . . . . . . . . . . 543MQCFT_* (Command structure type) . . . . 543MQCFUNC_* (CICS header function name) . . 544MQCGWI_* (CICS header get-wait interval) . . 544MQCHAD_* (Channel auto-definition eventreporting) . . . . . . . . . . . . . 544MQCHIDS_* (Channel indoubt status) . . . . 544MQCHS_* (Channel status). . . . . . . . 544MQCHSR_* (Channel stop requested) . . . . 545MQCHT_* (Channel type) . . . . . . . . 545MQCHTAB_* (Channel table) . . . . . . . 545MQCI_* (Correlation identifier) . . . . . . 545MQCIH_* (CICS header flags) . . . . . . . 546MQCIH_* (CICS header length) . . . . . . 546MQCIH_* (CICS header structure identifier) . . 546MQCIH_* (CICS header version) . . . . . . 546MQCLT_* (CICS header link type) . . . . . 546MQCMD_* (Command identifier) . . . . . 546MQCMDL_* (Command level) . . . . . . 547MQCNO_* (Connect options) . . . . . . . 548MQCNO_* (Connect options structure identifier) 548MQCNO_* (Connect options version) . . . . 548MQCO_* (Close options) . . . . . . . . 548MQCODL_* (CICS header output data length) 548MQCQT_* (Cluster queue type) . . . . . . 549MQCRC_* (CICS header return code) . . . . 549MQCSC_* (CICS header transaction start code) 549MQCTES_* (CICS header task end status) . . . 549MQCUOWC_* (CICS header unit-of-workcontrol) . . . . . . . . . . . . . . 549MQCXP_* (Channel-exit parameter structureidentifier). . . . . . . . . . . . . . 550MQCXP_* (Channel-exit parameter structureversion) . . . . . . . . . . . . . . 550MQDCC_* (Convert-characters masks andfactors) . . . . . . . . . . . . . . 550MQDCC_* (Convert-characters options) . . . 550MQDELO_* (Delete options) . . . . . . . 551MQDH_* (Distribution header structureidentifier). . . . . . . . . . . . . . 551MQDH_* (Distribution header version) . . . . 551MQDHF_* (Distribution header flags) . . . . 551MQDL_* (Distribution list support) . . . . . 551MQDLH_* (Dead-letter header structureidentifier). . . . . . . . . . . . . . 551MQDLH_* (Dead-letter header version) . . . 552MQDT_* (Destination type) . . . . . . . 552MQDXP_* (Data-conversion-exit parameterstructure identifier) . . . . . . . . . . 552MQDXP_* (Data-conversion-exit parameterstructure version) . . . . . . . . . . . 552MQEC_* (Signal event-control-block completioncode) . . . . . . . . . . . . . . . 552MQEI_* (Expiry interval) . . . . . . . . 552MQENC_* (Encoding) . . . . . . . . . 552MQENC_* (Encoding masks) . . . . . . . 553MQENC_* (Encoding for packed-decimalintegers) . . . . . . . . . . . . . . 553MQENC_* (Encoding for floating-pointnumbers) . . . . . . . . . . . . . . 553

Contents vii

||

||

||

||

||

||

||

||||

||

||

MQENC_* (Encoding for binary integers) . . . 553MQET_* (Escape type) . . . . . . . . . 554MQEVR_* (Event reporting) . . . . . . . 554MQFB_* (Feedback) . . . . . . . . . . 554MQFC_* (Force option) . . . . . . . . . 555MQFMT_* (Format) . . . . . . . . . . 555MQGI_* (Group identifier) . . . . . . . . 556MQGMO_* (Get message options) . . . . . 556MQGMO_* (Get message options structureidentifier). . . . . . . . . . . . . . 556MQGMO_* (Get message options version). . . 557MQGS_* (Group status) . . . . . . . . . 557MQHC_* (Connection handle) . . . . . . . 557MQHO_* (Object handle) . . . . . . . . 557MQIA_* (Integer attribute selector) . . . . . 557MQIACF_* (Integer attribute command formatparameter) . . . . . . . . . . . . . 558MQIACH_* (Channel integer attributecommand format parameter) . . . . . . . 559MQIAUT_* (IMS authenticator) . . . . . . 560MQIAV_* (Integer attribute value) . . . . . 560MQICM_* (IMS commit mode) . . . . . . 560MQIDO_* (Indoubt resolution) . . . . . . 561MQIIH_* (IMS header flags) . . . . . . . 561MQIIH_* (IMS header length) . . . . . . . 561MQIIH_* (IMS header structure identifier). . . 561MQIIH_* (IMS header version) . . . . . . 561MQISS_* (IMS security scope) . . . . . . . 561MQIT_* (Index type) . . . . . . . . . . 561MQITII_* (IMS transaction instance identifier) 562MQITS_* (IMS transaction state) . . . . . . 562MQMCAS_* (MCA status) . . . . . . . . 562MQMCAT_* (MCA type) . . . . . . . . 562MQMD_* (Message descriptor structureidentifier). . . . . . . . . . . . . . 562MQMD_* (Message descriptor version) . . . . 562MQMDE_* (Message descriptor extensionlength) . . . . . . . . . . . . . . 563MQMDE_* (Message descriptor extensionstructure identifier) . . . . . . . . . . 563MQMDE_* (Message descriptor extensionversion) . . . . . . . . . . . . . . 563MQMDEF_* (Message descriptor extensionflags) . . . . . . . . . . . . . . . 563MQMDS_* (Message delivery sequence) . . . 563MQMF_* (Message flags) . . . . . . . . 563MQMF_* (Message-flags masks) . . . . . . 564MQMI_* (Message identifier) . . . . . . . 564MQMO_* (Match options) . . . . . . . . 564MQMT_* (Message type) . . . . . . . . 564MQMTOK_* (Message token) . . . . . . . 564MQNC_* (Name count) . . . . . . . . . 565MQNPMS_* (Nonpersistent message speed) . . 565MQOD_* (Object descriptor length) . . . . . 565MQOD_* (Object descriptor structure identifier) 565MQOD_* (Object descriptor version) . . . . 565MQOII_* (Object instance identifier) . . . . . 565MQOL_* (Original length) . . . . . . . . 566MQOO_* (Open options) . . . . . . . . 566MQOT_* (Object type) . . . . . . . . . 566MQPA_* (Put authority) . . . . . . . . . 567

MQPER_* (Persistence) . . . . . . . . . 567MQPL_* (Platform) . . . . . . . . . . 567MQPMO_* (Put message options) . . . . . 567MQPMO_* (Put message options structurelength) . . . . . . . . . . . . . . 568MQPMO_* (Put message options structureidentifier). . . . . . . . . . . . . . 568MQPMO_* (Put message options version) . . . 568MQPMRF_* (Put message record field flags) . . 568MQPO_* (Purge option) . . . . . . . . . 568MQPRI_* (Priority) . . . . . . . . . . 568MQPS_* (Publish/subscribe tags). . . . . . 568MQPS_* (Publish/subscribe tag commands) . . 570MQPS_* (Publish/subscribe tag options) . . . 570MQPUBO_* (Publication options). . . . . . 571MQPXP_* (Publish/subscribe routing exitstructure identifier) . . . . . . . . . . 571MQPXP_* (Publish/subscribe routing exitversion) . . . . . . . . . . . . . . 572MQQA_* (Inhibit get) . . . . . . . . . 572MQQA_* (Inhibit put) . . . . . . . . . 572MQQA_* (Backout hardening). . . . . . . 572MQQA_* (Queue shareability) . . . . . . . 572MQQDT_* (Queue definition type) . . . . . 572MQQF_* (Queue flags) . . . . . . . . . 572MQQMF_* (Queue-manager flags) . . . . . 573MQQMDT_* (Queue-manager definition type) 573MQQMT_* (Queue-manager type) . . . . . 573MQQO_* (Quiesce option) . . . . . . . . 573MQQSIE_* (Service interval events) . . . . . 573MQQT_* (Queue type) . . . . . . . . . 573MQRC_* (Reason code) . . . . . . . . . 574MQRCCF_* (Reason code for command format) 579MQREGO_* (Registration options) . . . . . 582MQRFH_* (Rules and formatting header flags) 582MQRFH_* (Rules and formatting header length) 582MQRFH_* (Rules and formatting headerstructure identifier) . . . . . . . . . . 582MQRFH_* (Rules and formatting headerversion) . . . . . . . . . . . . . . 582MQRL_* (Returned length) . . . . . . . . 582MQRMH_* (Reference message header structureidentifier). . . . . . . . . . . . . . 583MQRMH_* (Reference message header version) 583MQRMHF_* (Reference message header flags) 583MQRO_* (Report options) . . . . . . . . 583MQRO_* (Report-options masks) . . . . . . 584MQRP_* (Replace option) . . . . . . . . 584MQRQ_* (Reason qualifier). . . . . . . . 584MQSCO_* (Queue scope) . . . . . . . . 584MQSEG_* (Segmentation) . . . . . . . . 584MQSID_* (Security identifier) . . . . . . . 584MQSIDT_* (Security identifier type) . . . . . 585MQSP_* (Syncpoint) . . . . . . . . . . 585MQSS_* (Segment status) . . . . . . . . 585MQSUS_* (Suspend status) . . . . . . . . 585MQTC_* (Trigger control) . . . . . . . . 585MQTM_* (Trigger message structure identifier) 585MQTM_* (Trigger message version) . . . . . 586MQTMC_* (Trigger message character formatstructure identifier) . . . . . . . . . . 586

viii MQSeries Application Programming Reference

||

||

||

MQTMC_* (Trigger message character formatversion) . . . . . . . . . . . . . . 586MQTT_* (Trigger type) . . . . . . . . . 586MQTXP_* (Transport retry exit structureidentifier). . . . . . . . . . . . . . 586MQTXP_* (Transport retry exit version) . . . 587MQUA_* (User-attribute selectors) . . . . . 587MQUS_* (Usage) . . . . . . . . . . . 587MQWDR_* (Cluster workload exitdestination-record length) . . . . . . . . 587MQWDR_* (Cluster workload exitdestination-record structure identifier) . . . . 587MQWDR_* (Cluster workload exitdestination-record version) . . . . . . . . 587MQWI_* (Wait interval) . . . . . . . . . 587MQWIH_* (Workload information header flags) 588MQWIH_* (Workload information headerstructure length) . . . . . . . . . . . 588MQWIH_* (Workload information headerstructure identifier) . . . . . . . . . . 588MQWIH_* (Workload information headerversion) . . . . . . . . . . . . . . 588MQWQR_* (Cluster workload exit queue-recordlength) . . . . . . . . . . . . . . 588MQWQR_* (Cluster workload exit queue-recordstructure identifier) . . . . . . . . . . 588MQWQR_* (Cluster workload exit queue-recordversion) . . . . . . . . . . . . . . 589MQWXP_* (Cluster workload exit structureidentifier). . . . . . . . . . . . . . 589MQWXP_* (Cluster workload exit version) . . 589MQXC_* (Exit command identifier) . . . . . 589MQXCC_* (Exit response) . . . . . . . . 589MQXDR_* (Data-conversion-exit response) . . 590MQXP_* (Exit parameter block structureidentifier). . . . . . . . . . . . . . 590MQXP_* (Exit parameter block version) . . . 590MQXPT_* (Transmission protocol type). . . . 590MQXQH_* (Transmission queue headerstructure identifier) . . . . . . . . . . 590MQXQH_* (Transmission queue header version) 590MQXR_* (Exit reason) . . . . . . . . . 591MQXR2_* (Secondary exit response) . . . . . 591MQXT_* (Exit identifier). . . . . . . . . 591MQXUA_* (Exit user area) . . . . . . . . 592MQXWD_* (Exit wait descriptor structureidentifier). . . . . . . . . . . . . . 592MQXWD_* (Exit wait descriptor version) . . . 592MQZAET_* (Authority service entity type) . . 592MQZAO_* (Authority service authorizationtype) . . . . . . . . . . . . . . . 592MQZAS_* (Authority service version) . . . . 593MQZED_* (Entity descriptor structure identifier) 593MQZED_* (Entity descriptor version) . . . . 593MQZCI_* (Continuation indicator) . . . . . 593MQZID_* (Function identifier, all services) . . 593MQZID_* (Function identifier, authority service) 593MQZID_* (Function identifier, name service) 594MQZID_* (Function identifier, userid service) 594MQZIO_* (Initialization options) . . . . . . 594MQZNS_* (Name service version) . . . . . 594

MQZTO_* (Termination options) . . . . . . 594MQZUS_* (Userid service version) . . . . . 594

Appendix C. Rules for validating MQIoptions . . . . . . . . . . . . . . 595MQOPEN call . . . . . . . . . . . . . 595MQPUT call . . . . . . . . . . . . . . 595MQPUT1 call . . . . . . . . . . . . . 596MQGET call . . . . . . . . . . . . . . 596MQCLOSE call . . . . . . . . . . . . . 596

Appendix D. Machine encodings . . . 597Binary-integer encoding . . . . . . . . . . 597Packed-decimal-integer encoding . . . . . . . 598Floating-point encoding . . . . . . . . . . 598Constructing encodings . . . . . . . . . . 599Analyzing encodings . . . . . . . . . . . 599

Using bit operations . . . . . . . . . . 599Using arithmetic . . . . . . . . . . . 600

Summary of machine architecture encodings . . . 600

Appendix E. Report options andmessage flags . . . . . . . . . . . 601Structure of the report field. . . . . . . . . 601Analyzing the report field . . . . . . . . . 602

Using bit operations . . . . . . . . . . 603Using arithmetic . . . . . . . . . . . 603

Structure of the message-flags field . . . . . . 604

Appendix F. Data conversion . . . . . 607Conversion processing . . . . . . . . . . 607Processing conventions . . . . . . . . . . 609Conversion of report messages . . . . . . . 613MQDXP – Data-conversion exit parameter. . . . 615

Fields . . . . . . . . . . . . . . . 615C declaration . . . . . . . . . . . . 620COBOL declaration . . . . . . . . . . 620System/390 assembler declaration . . . . . 621

MQXCNVC - Convert characters . . . . . . . 621Syntax. . . . . . . . . . . . . . . 621Parameters . . . . . . . . . . . . . 621C invocation. . . . . . . . . . . . . 626COBOL invocation (OS/400 only) . . . . . 626System/390 assembler invocation (OS/390 only) 627

MQ_DATA_CONV_EXIT - Data conversion exit 627Syntax. . . . . . . . . . . . . . . 627Parameters . . . . . . . . . . . . . 628Usage notes . . . . . . . . . . . . . 629C invocation. . . . . . . . . . . . . 631COBOL invocation (OS/400 only) . . . . . 632System/390 assembler invocation (OS/390 only) 632

Appendix G. Signal notification IPCmessage (Tandem NSK only) . . . . 633

Appendix H. Code page conversiontables . . . . . . . . . . . . . . . 635Codeset names and CCSIDs . . . . . . . . 636Code page conversion tables . . . . . . . . 637

Contents ix

|||||

MVS/ESA single byte conversion support . . . . 679OS/2 conversion support . . . . . . . . . 684OS/400 conversion support . . . . . . . . 685Unicode conversion support . . . . . . . . 685

MQSeries OS/2 support for Unicode . . . . 685MQSeries AIX support for Unicode . . . . . 685MQSeries HP-UX support for Unicode . . . . 686MQSeries NT and Solaris support for Unicode 686OS/400 support for Unicode . . . . . . . 687

Appendix I. Notices . . . . . . . . . 689Programming interface information . . . . . . 690Trademarks . . . . . . . . . . . . . . 691

Glossary of terms and abbreviations 693

Bibliography . . . . . . . . . . . . 705

MQSeries cross-platform publications . . . . . 705MQSeries platform-specific publications . . . . 707Softcopy books . . . . . . . . . . . . . 708

BookManager format . . . . . . . . . . 708HTML format . . . . . . . . . . . . 708Portable Document Format (PDF) . . . . . 708PostScript format . . . . . . . . . . . 708Windows Help format . . . . . . . . . 708

MQSeries information available on the Internet . . 708Related publications . . . . . . . . . . . 708

Index . . . . . . . . . . . . . . . 709

Sending your comments to IBM . . . 717

x MQSeries Application Programming Reference

Tables

1. Short names used for supported environments xiv2. C and C++ language compilers. . . . . . xvi3. COBOL language compilers . . . . . . xvii4. PL/I language compilers . . . . . . . xvii5. Visual Basic language compilers . . . . . xvii6. Assembler/390 language compilers . . . . xvii7. TAL compilers . . . . . . . . . . . xviii8. Elementary data types in C . . . . . . . 79. Elementary data types in COBOL . . . . . 8

10. Elementary data types in PL/I . . . . . . 811. Elementary data types in System/390 assembler 912. Elementary data types in TAL . . . . . . 1013. Elementary data types in Visual Basic . . . . 1014. C header file . . . . . . . . . . . . 1515. COBOL COPY files . . . . . . . . . . 1816. PL/I INCLUDE file . . . . . . . . . . 2017. Assembler macros . . . . . . . . . . 2218. Visual Basic header files . . . . . . . . 2419. Fields in MQBO . . . . . . . . . . . 2720. Initial values of fields in MQBO. . . . . . 2821. Fields in MQCIH. . . . . . . . . . . 2922. Contents of error information fields in MQCIH

structure . . . . . . . . . . . . . 3023. Initial values of fields in MQCIH . . . . . 4124. Fields in MQCNO . . . . . . . . . . 4725. Initial values of fields in MQCNO . . . . . 5226. Fields in MQDH . . . . . . . . . . . 5527. Initial values of fields in MQDH . . . . . 5928. Fields in MQDLH . . . . . . . . . . 6329. Initial values of fields in MQDLH . . . . . 6930. Fields in MQGMO . . . . . . . . . . 7331. MQGET options relating to messages in

groups and segments of logical messages . . 9032. Outcome when MQGET or MQCLOSE call not

consistent with group and segmentinformation . . . . . . . . . . . . 92

33. Initial values of fields in MQGMO . . . . 10534. Fields in MQIIH . . . . . . . . . . 10935. Initial values of fields in MQIIH . . . . . 11336. Fields in MQMD . . . . . . . . . . 11737. Initial values of fields in MQMD . . . . . 17038. Fields in MQMDE . . . . . . . . . . 17739. Queue-manager action when MQMDE

specified on MQPUT or MQPUT1. . . . . 17840. Initial values of fields in MQMDE . . . . 18241. Fields in MQOD . . . . . . . . . . 18542. Initial values of fields in MQOD . . . . . 19543. Fields in MQOR . . . . . . . . . . 19944. Initial values of fields in MQOR . . . . . 20045. Fields in MQPMO . . . . . . . . . . 20146. MQPUT options relating to messages in

groups and segments of logical messages . . 20647. Outcome when MQPUT or MQCLOSE call

not consistent with group and segmentinformation . . . . . . . . . . . . 208

48. Initial values of fields in MQPMO . . . . 218

49. Fields in MQPMR . . . . . . . . . . 22350. Fields in MQRMH . . . . . . . . . . 22751. Initial values of fields in MQRMH . . . . 23452. Fields in MQRR. . . . . . . . . . . 23953. Initial values of fields in MQRR . . . . . 24054. Fields in MQTM . . . . . . . . . . 24155. Initial values of fields in MQTM . . . . . 24656. Fields in MQTMC2 . . . . . . . . . 24957. Initial values of fields in MQTMC2 . . . . 25158. Fields in MQWIH . . . . . . . . . . 25559. Initial values of fields in MQWIH. . . . . 25760. Fields in MQXP. . . . . . . . . . . 26161. Fields in MQXQH . . . . . . . . . . 26762. Initial values of fields in MQXQH . . . . 27163. Effect of MQCLOSE options on various types

of object and queue . . . . . . . . . 29364. Valid MQOPEN options for each queue type 35365. Attributes for all queues . . . . . . . . 40166. Attributes for local and model queues 40767. Attributes for local definitions of remote

queues . . . . . . . . . . . . . . 42568. Attributes for namelists . . . . . . . . 42969. Attributes for process definitions . . . . . 43170. Attributes for the queue manager . . . . . 43571. Summary of encodings for machine

architectures . . . . . . . . . . . . 60072. Fields in MQDXP . . . . . . . . . . 61573. Codeset names and CCSIDs. . . . . . . 63674. Conversion support: US ENGLISH . . . . 63875. Conversion support: GERMAN . . . . . 64076. Conversion support: DANISH and

NORWEGIAN . . . . . . . . . . . 64277. Conversion support: FINNISH and SWEDISH 64478. Conversion support: ITALIAN . . . . . . 64579. Conversion support: SPANISH. . . . . . 64780. Conversion support: UK ENGLISH /

GAELIC . . . . . . . . . . . . . 64981. Conversion support: FRENCH . . . . . . 65182. Conversion support: MULTILINGUAL 65383. Conversion support: PORTUGUESE . . . . 65584. Conversion support: ICELANDIC. . . . . 65685. Conversion support: EASTERN EUROPEAN

Languages . . . . . . . . . . . . 65886. Conversion support: CYRILLIC . . . . . 65987. Conversion support: ESTONIAN . . . . . 66088. Conversion support: LATVIAN and

LITHUANIAN . . . . . . . . . . . 66189. Conversion support: UKRAINIAN . . . . 66290. Conversion support: GREEK . . . . . . 66391. Conversion support: TURKISH . . . . . 66492. Conversion support: HEBREW. . . . . . 66593. Conversion support: ARABIC . . . . . . 66694. Conversion support: FARSI . . . . . . . 66795. Conversion support: URDU. . . . . . . 66896. Conversion support: THAI . . . . . . . 66997. Conversion support: LAO . . . . . . . 670

© Copyright IBM Corp. 1994, 2000 xi

98. Conversion support: VIETNAMESE . . . . 67199. Conversion support: JAPANESE LATIN SBCS 672

100. Conversion support: JAPANESE KATAKANASBCS . . . . . . . . . . . . . . 673

101. Conversion support: JAPANESE KANJI /LATIN MIXED . . . . . . . . . . . 674

102. Conversion support: JAPANESE KANJI /KATAKANA MIXED . . . . . . . . . 675

103. Conversion support: KOREAN. . . . . . 676104. Conversion support: SIMPLIFIED CHINESE 677105. Conversion support: TRADITIONAL

CHINESE . . . . . . . . . . . . . 678106. MQSeries for OS/390 V2.1 single byte CCSID

conversion support . . . . . . . . . 679

xii MQSeries Application Programming Reference

About this book

The IBM® MQSeries set of products provides application programming services, onvarious platforms, that allow a new style of programming. This style enables youto code indirect program-to-program communication using message queues.

This book gives a full description of the MQSeries programming interface, theMQI, for the following products:

MQSeries for AIX Version 5.1MQSeries for AS/400 Version 5 Release 1MQSeries for AT&T GIS UNIX Version 2 Release 21MQSeries for Digital OpenVMS Version 2 Release 2MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)MQSeries for HP-UX Version 5.1MQSeries for OS/2 Warp Version 5.1MQSeries for OS/390 Version 2 Release 1MQSeries for SINIX and DC/OSx Version 2.2MQSeries for Sun Solaris Version 5.1MQSeries for Tandem NonStop Kernel Version 2 Release 2.1MQSeries for VSE/ESA Version 2 Release 1MQSeries for Windows NT Version 5.1MQSeries for Windows Version 2.0MQSeries for Windows Version 2.1

Notes:

1. This book does not apply to the MQSeries for AS/400 Version 5 Release 1product using the RPG programming language.You should use the MQSeries for AS/400 Version 5 Release 1 ApplicationProgramming Reference (ILE RPG) manual, SC34-5559 for this programminglanguage.

2. C++This book does not describe the C++ programming language binding. Forinformation on C++ you should see the MQSeries Using C++ book.

For information on how to design and write applications that use the servicesMQSeries provides, see the MQSeries Application Programming Guide.

Who this book is forThis book is for the designers of applications that use message queuing techniques,and for programmers who have to implement these designs.

What you need to know to understand this bookTo write message queuing applications using MQSeries, you need to know how towrite programs in one of the supported programming languages:v C or COBOL (available on all supported platforms)v PL/I (available on AIX, OS/2, OS/390, VSE/ESA, and Windows NT)v System/390® assembler (available on OS/390 only)

1. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1994, 2000 xiii

|

v TAL (available on Tandem NonStop Kernel only)v Visual Basic V4 or V5 (available on Windows 3.1, Windows 95, Windows 98, and

Windows NT only)

If the applications you are writing are to run within a CICS® system, you mustalso be familiar with CICS on your platform and its application programminginterface.

To understand this book, you do not need to have written message queuingprograms before.

How to use this bookThis book enables you to find out quickly, for example, how to use a particular callor how to correct a particular error situation.

The book presents detailed reference information about the MQSeriesprogramming interface, called the Message Queue Interface (MQI). It describes the:v Data types that the MQI calls usev Parameters and return codes for the callsv Attributes of MQSeries objectsv Values of constants you need to use when you write MQSeries programsv Reason codes that may occur when you run your programs

Appearance of text in this bookThis book uses the following type styles:MQOPEN

Example of the name of a callCompCode

Example of the name of a parameter of a call, a field in a structure, or theattribute of an object

MQMDExample of the name of a data type or structure

MQCC_FAILEDExample of the name of a constant

Terms used in this bookAll new terms that this book introduces are defined in the glossary. In the body ofthis book, the following shortened names are used for these products:MQSeries

The MQSeries set of productsCICS The CICS, or Transaction Server, product for the specific platform on which

you are working.

Not all of the capabilities described in this book are available in all environments.Those calls, structures, fields, or options that are not supported everywhere areidentified as such in the explanatory text. Table 1 shows the short names used inthis book for the various environments, and the products to which they refer.

Table 1. Short names used for supported environments

Short name used in this book Full product or environment name

AIX MQSeries for AIX Version 5.1

DOS client MQ client applications running on PC-DOS

About this book

xiv MQSeries Application Programming Reference

Table 1. Short names used for supported environments (continued)

Short name used in this book Full product or environment name

HP-UX MQSeries for HP-UX Version 5.1

OS/390 MQSeries for OS/390 Version 2.1

Compaq (DIGITAL) OpenVMS MQSeries for Digital OpenVMS Version 2.2

OS/2 MQSeries for OS/2 Warp Version 5.1

OS/400 MQSeries for AS/400 Version 5R1

Sun Solaris MQSeries for Sun Solaris Version 5.1

Tandem NonStop Kernel MQSeries for Tandem NonStop Kernel Version 2.2

UNIX® systems The UNIX systems supported by MQSeries that are not Version 5. These are:v MQSeries for AT&T GIS UNIX, Version 2.2v MQSeries for SINIX and DC/OSx Version 2.2v MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

Windows client MQSeries client applications running on Windows 3.1, Windows 95, Windows 98,or Windows NT

Windows NT MQSeries for Windows NT Version 5.1

16-bit Windows MQSeries for Windows Version 2.0

32-bit Windows MQSeries for Windows Version 2.1

The following table lists the MQSeries products available for Windows, and showsthe Windows platforms on which each runs.

Product Windows 3.1 Windows 95 Windows 98 Windows NT

MQSeries for Windows Client Yes Yes Yes Yes

MQSeries for Windows NT No No No Yes

MQSeries for Windows V2.0 Yes Yes No No

MQSeries for Windows V2.1 No Yes Yes Yes

MQSeries for Windows Versions 2.0 and 2.1 support most of the features of theMQI described in this book. For information on these products, see the MQSeriesfor Windows User’s Guide.

Language compilersAlso, we use the following shortened names for these language compilers:v C – see Table 2 on page xviv COBOL – see Table 3 on page xviiv PL/I – see Table 4 on page xviiv Visual Basic – see Table 5 on page xviiv Assembler/390 – see Table 6 on page xviiv TAL – see Table 7 on page xviii

About this book

About this book xv

Table 2. C and C++ language compilers

Platform Compiler

AIX IBM C for AIX Version 3.1.4 IBM C Set++ for AIX V3.1

AIX C++ IBM C Set++ for AIX V3.1

AS/400 IBM ILE C for AS/400, V4R4M0

AS/400 C++ IBM VisualAge™ C++ compiler for AS/400, 5716-CX4 PRPQ ILE C++compiler for AS/400, 5799-GDW

AT&T AT&T GIS High Performance C V1.0b compiler

AT&T C++ AT&T C++ language system for AT&T GIS UNIX

DC/OSx DC/OSx C4.0 Version 4.0.1 compiler

Digital OpenVMS DEC C Version 5.0

Digital OpenVMS C++ DEC C++ V5.0 (VAX) V5.2 (AXP)

Digital UNIX DEC C V5.2 for Digital UNIX

HP-UX C Softbench Version 5.0 HP-UX ANSI C HP C++, V3.1 for HP-UX V10.xHP C, V3.6 for HP-UX

HP-UX C++ HP C++, V3.1 for HP-UX V10.x IBM C and C++ compiler, V3.6 HP-UXANSI C++ for V10 and V11 ANSI C++ compiler V3.6

OS/2 IBM VisualAge for C++ for OS/2 V3.0 Borland C++ V2.0 (C bindingsonly) IBM C and C++ compiler, V3.6

OS/2 C++ IBM VisualAge for C++ for OS/2, V3.0

OS/390 C/370™ Release 2.1.0 IBM SAA AD/Cycle™ C/370 Compiler

OS/390 C++ IBM OS/390 C/C++ V2R4 IBM OS/390 C/C++

SINIX C compiler (C-DS, MIPS) V1.1

Sun Solaris Sun WorkShop Compiler C V4.2

Sun Solaris C++ Sun WorkShop Compiler C++ V4.2

Tandem NSK D30 or later using the WIDE memory model (32-bit integers)

VSE/ESA IBM C for VSE/ESA V1.1

Windows NT Microsoft Visual C++ for Windows 95 and Windows NT V4.0 IBMVisualAge for C++ for Windows V3.5

Windows NT C++ IBM VisualAge for C++ for Windows V3.5 Microsoft Visual C++ forWindows 95 and Windows NT V4.0 IBM VisualAge for C++ ProfessionalV4.0 IBM VisualAge for C++ Professional V5.0 IBM C and C++ compiler,V3.6.4

MQSeries for Windows V2.0 - 16-bit 16-bit C - Microsoft Visual C++ V1.5

MQSeries for Windows V2.0- 32-bit 32-bit C - Microsoft Visual C++ V2.0

MQSeries for Windows V2.1 Microsoft Visual C++ V4.0 Borland C

DOS clients Microsoft C V7 Microsoft Visual C++ V1.5

Windows 3.1 clients Microsoft C V7.0

Windows 3.1 clients C++ Microsoft Visual C++ V2.0

Windows 95 and Windows 98 clients Microsoft Visual C++ V2.0

Windows 95 and Windows 98 clients C++ IBM VisualAge for C++ V3.5 Microsoft Visual C++ V4.0

Note: AT&T has become NCR UNIX SVR4 MP-RAS, R3.0

About this book

xvi MQSeries Application Programming Reference

Table 3. COBOL language compilers

Platform Compiler

AIX The Micro Focus COBOL compiler V4.0 for UNIX Systems IBM COBOLSet for AIX Version 1.1

AS/400 IBM ILE COBOL compiler for AS/400 V4R4M0

Digital OpenVMS DEC COBOL V5.0 (VAX) V2.2 (AXP)

HP-UX COBOL Softbench Version 4.0 Micro Focus COBOL compiler Version 4.0for UNIX Systems

OS/2 Micro Focus COBOL compiler V4.0 IBM VisualAge for COBOL for OS/2V1.1

OS/390 IBM COBOL for MVS and VM (formerly COBOL/370™) IBM COBOL forOS/390 and VM

SINIX and DC/OSx Micro Focus COBOL compiler V3.2 for SINIX

Sun Solaris Micro Focus COBOL compiler for UNIX systems V4.0

Tandem NSK D30 or later

VSE/ESA IBM COBOL for VSE/ESA V1.1

Windows NT Micro Focus Object COBOL compiler V3.3 or V4.0 for Windows NT IBMVisualAge COBOL Enterprise V2.2 IBM VisualAge COBOL forWindows NT V2.1

Windows 95 and Windows 98 clients Micro Focus COBOL Workbench V4.0

Table 4. PL/I language compilers

Platform Compiler

AIX IBM PL/I Set for AIX V1.1

OS/2 IBM Visual Age for PL/I for OS/2 IBM PL/I for OS/2 V1.2

OS/390 IBM SAA AD/Cycle PL/I IBM PL/I for MVS and VM

VSE/ESA IBM PL/I for VSE/ESA V1.1

Windows NT IBM Visual Age for PL/I for Windows IBM PL/I for Windows V1.2 IBMVisualAge PL/I Enterprise V2.1

In addition, MQSeries for Windows V2.0, MQSeries for Windows V2.1, andMQSeries for Windows NT V5.1 support Basic compilers.

Table 5. Visual Basic language compilers

Platform Compiler

MQSeries for Windows V2.0 - 16-bit Microsoft Visual Basic V4.0 (16 bit)

MQSeries for Windows V2.0 - 32-bit Microsoft Visual Basic V4.0 (32 bit)

MQSeries for Windows V2.1 Microsoft Visual Basic V4.0

MQSeries for Windows NT V5.1 Microsoft Visual Basic V4.0 or V5.0

Windows 3.1 clients Microsoft Visual Basic V4.0

Windows 95 and Windows 98 clients Microsoft Visual Basic V4.0 or V5.0

Table 6. Assembler/390 language compilers

Platform Compiler

OS/390 Assembler H assembler IBM High Level Assembler/MVS assembler

About this book

About this book xvii

Table 7. TAL compilers

Platform Compiler

Tandem NSK D30 or later IBM High Level Assembler/MVS assembler

About this book

xviii MQSeries Application Programming Reference

Summary of changes

This section describes changes to this edition of MQSeries Application ProgrammingReference. Changes since the previous edition of the book are marked by verticallines to the left of the changes.

Changes for this edition (SC33-1673-06)Major changes for this edition include:v Addition of the MQSeries for AS/400 V5R1 product.

Changes for the previous edition included:v Addition of the following versions and releases of MQSeries products:

– MQSeries for AIX V5.1– MQSeries for AS/400 V4R2M1– MQSeries for HP-UX V5.1– MQSeries for OS/2 Warp V5.1– MQSeries for OS/390 V2.1– MQSeries for Sun Solaris V5.1– MQSeries for VSE/ESA V2.1– MQSeries for Windows NT V5.1

v Addition of the MQWIH structurev Addition of cluster supportv Addition of code pages supporting the euro currency symbol

Changes for the fifth edition included:Changes to the book for the fifth edition included:v New versions of the following products:

– MQSeries for AS/400– MQSeries for Tandem NonStop Kernel

© Copyright IBM Corp. 1994, 2000 xix

|

||

|

|

|

Changes

xx MQSeries Application Programming Reference

Part 1. Data type descriptions

Chapter 1. Elementary data types . . . . . . . 5Conventions used in the descriptions of data types . 5Elementary data types . . . . . . . . . . . 5

MQBYTE - Byte . . . . . . . . . . . . 5MQBYTEn - String of n bytes . . . . . . . . 5MQCHAR - character . . . . . . . . . . 6MQCHARn - String of n characters . . . . . . 6MQHCONN - Connection handle . . . . . . 6MQHOBJ - Object handle . . . . . . . . . 6MQLONG - Long integer . . . . . . . . . 7Elementary data types - C programming language 7Elementary data types - COBOL programminglanguage. . . . . . . . . . . . . . . 8Elementary data types - PL/I language (AIX,OS/2, OS/390, VSE/ESA, and Windows NT only) . 8Elementary data types - System/390 Assembler(OS/390 only) . . . . . . . . . . . . . 9Elementary data types - TAL programminglanguage (Tandem NonStop Kernel only) . . . 10Elementary data types - Visual Basic (Windows3.1, Windows 95, Windows 98, and Windows NT) 10

Chapter 2. Structure data types – programmingconsiderations . . . . . . . . . . . . . 13Conventions used in the descriptions of data types 13Language considerations . . . . . . . . . . 14

Using the data types in the C programminglanguage . . . . . . . . . . . . . . 14

Header files . . . . . . . . . . . . 15Functions . . . . . . . . . . . . . 15Parameters with undefined data type. . . . 15Data types. . . . . . . . . . . . . 15Manipulating binary strings . . . . . . . 16Manipulating character strings . . . . . . 16Initial values for structures . . . . . . . 16Initial values for dynamic structures . . . . 17Use from C++ . . . . . . . . . . . 17Notational conventions . . . . . . . . 17

Using the data types in the COBOLprogramming language . . . . . . . . . 17

COPY files. . . . . . . . . . . . . 18Structures . . . . . . . . . . . . . 18Pointers . . . . . . . . . . . . . 19Named constants . . . . . . . . . . 19Notational conventions . . . . . . . . 20

Using the data types in the PL/I programminglanguage . . . . . . . . . . . . . . 20

INCLUDE files . . . . . . . . . . . 20Structures . . . . . . . . . . . . . 21Named constants . . . . . . . . . . 21Notational conventions . . . . . . . . 21

Using the data types in the System/390Assembler programming language . . . . . 22

Macros . . . . . . . . . . . . . . 22Names . . . . . . . . . . . . . . 22Structures . . . . . . . . . . . . . 22

Notational conventions . . . . . . . . 23Using the data types in the Visual Basicprogramming language . . . . . . . . . 24

Header files in Visual Basic . . . . . . . 24Parameters of the MQI calls . . . . . . . 24Initial values for structures . . . . . . . 24Notational conventions . . . . . . . . 24

Structure data types . . . . . . . . . . . 25

Chapter 3. MQBO - Begin options . . . . . . 27Overview . . . . . . . . . . . . . . . 27Fields . . . . . . . . . . . . . . . . 27Initial values and language declarations . . . . . 28


Chapter 4. MQCIH - CICS bridge header . . . . 29Overview . . . . . . . . . . . . . . . 30Fields . . . . . . . . . . . . . . . . 31Initial values and language declarations . . . . . 41

C declaration . . . . . . . . . . . . . 42COBOL declaration . . . . . . . . . . . 42PL/I declaration . . . . . . . . . . . . 44System/390 assembler declaration . . . . . . 44

Chapter 5. MQCNO - Connect options . . . . . 47Overview . . . . . . . . . . . . . . . 47Fields . . . . . . . . . . . . . . . . 47Initial values and language declarations . . . . . 52


Chapter 6. MQDH - Distribution header . . . . 55Overview . . . . . . . . . . . . . . . 55Fields . . . . . . . . . . . . . . . . 56Initial values and language declarations . . . . . 59


Chapter 7. MQDLH - Dead-letter header . . . . 63Overview . . . . . . . . . . . . . . . 63Fields . . . . . . . . . . . . . . . . 65Initial values and language declarations . . . . . 69

C declaration . . . . . . . . . . . . . 70COBOL declaration . . . . . . . . . . . 70PL/I declaration . . . . . . . . . . . . 71System/390 assembler declaration . . . . . . 71TAL declaration . . . . . . . . . . . . 72Visual Basic declaration . . . . . . . . . 72

© Copyright IBM Corp. 1994, 2000 1

Chapter 8. MQGMO - Get-message options . . . 73Overview . . . . . . . . . . . . . . . 73Fields . . . . . . . . . . . . . . . . 73Initial values and language declarations . . . . 105


Chapter 9. MQIIH - IMS bridge header . . . . 109Overview. . . . . . . . . . . . . . . 109Fields . . . . . . . . . . . . . . . . 110Initial values and language declarations . . . . 113


Chapter 10. MQMD - Message descriptor . . . 117Overview. . . . . . . . . . . . . . . 118Fields . . . . . . . . . . . . . . . . 119Initial values and language declarations . . . . 170


Chapter 11. MQMDE - Message descriptorextension . . . . . . . . . . . . . . 177Overview. . . . . . . . . . . . . . . 177Fields . . . . . . . . . . . . . . . . 179Initial values and language declarations . . . . 182


Chapter 12. MQOD - Object descriptor . . . . 185Overview. . . . . . . . . . . . . . . 185Fields . . . . . . . . . . . . . . . . 186Initial values and language declarations . . . . 195


Chapter 13. MQOR - Object record . . . . . 199Overview. . . . . . . . . . . . . . . 199Fields . . . . . . . . . . . . . . . . 199Initial values and language declarations . . . . 200


Chapter 14. MQPMO - Put message options . . 201Overview. . . . . . . . . . . . . . . 201Fields . . . . . . . . . . . . . . . . 202Initial values and language declarations . . . . 218


Chapter 15. MQPMR - Put-message record . . 223Overview. . . . . . . . . . . . . . . 223Fields . . . . . . . . . . . . . . . . 223Initial values and language declarations . . . . 225


Chapter 16. MQRMH - Message referenceheader . . . . . . . . . . . . . . . 227Overview. . . . . . . . . . . . . . . 227Fields . . . . . . . . . . . . . . . . 228Initial values and language declarations . . . . 234


Chapter 17. MQRR - Response record . . . . 239Overview. . . . . . . . . . . . . . . 239Fields . . . . . . . . . . . . . . . . 239Initial values and language declarations . . . . 240


Chapter 18. MQTM - Trigger message . . . . 241Overview. . . . . . . . . . . . . . . 241Fields . . . . . . . . . . . . . . . . 243Initial values and language declarations . . . . 246


Chapter 19. MQTMC2 - Trigger message 2(character format) . . . . . . . . . . . 249Overview. . . . . . . . . . . . . . . 249Fields . . . . . . . . . . . . . . . . 250Initial values and language declarations . . . . 251

C declaration . . . . . . . . . . . . 251COBOL declaration . . . . . . . . . . 252PL/I declaration . . . . . . . . . . . 252System/390 assembler declaration . . . . . 252TAL declaration . . . . . . . . . . . 252

Data types

2 MQSeries Application Programming Reference

Visual Basic declaration . . . . . . . . . 253

Chapter 20. MQWIH - Work information header 255Overview. . . . . . . . . . . . . . . 255Fields . . . . . . . . . . . . . . . . 255Initial values and language declarations . . . . 257


Chapter 21. MQXP - Exit parameter block(OS/390 only) . . . . . . . . . . . . . 261Overview. . . . . . . . . . . . . . . 261Fields . . . . . . . . . . . . . . . . 261Language declarations . . . . . . . . . . 264


Chapter 22. MQXQH - Transmission queueheader . . . . . . . . . . . . . . . 267Overview. . . . . . . . . . . . . . . 267Fields . . . . . . . . . . . . . . . . 270Initial values and language declarations . . . . 271


Data types

Part 1. Data type descriptions 3

Data types


Chapter 1. Elementary data types

This chapter describes the elementary data types used by the MQI.

The elementary data types are:v MQBYTE – Bytev MQBYTEn – String of n bytesv MQCHAR – Single-byte characterv MQCHARn – String of n single-byte charactersv MQHCONN – Connection handlev MQHOBJ – Object handlev MQLONG – Long integer

Conventions used in the descriptions of data typesFor each elementary data type, this chapter gives a description of its usage, in aform that is independent of the programming language. This is followed by typicaldeclarations in each of the supported programming languages.

Elementary data typesAll of the other data types described in this chapter equate either directly to theseelementary data types, or to aggregates of these elementary data types (arrays orstructures).

MQBYTE - ByteThe MQBYTE data type represents a single byte of data. No particularinterpretation is placed on the byte—it is treated as a string of bits, and not as abinary number or character. No special alignment is required.

An array of MQBYTE is sometimes used to represent an area of main storagewhose nature is not known to the queue manager. For example, the area maycontain application message data or a structure. The boundary alignment of thisarea must be compatible with the nature of the data contained within it.

In the C programming language, any data type can be used for functionparameters that are shown as arrays of MQBYTE. This is because such parametersare always passed by address, and in C the function parameter is declared as apointer-to-void.

MQBYTEn - String of n bytesEach MQBYTEn data type represents a string of n bytes, where n can take one ofthe following values:

16, 24, 32, 40, or 64

Each byte is described by the MQBYTE data type. No special alignment isrequired.

If the data in the string is shorter than the defined length of the string, the datamust be padded with nulls to fill the string.


When the queue manager returns byte strings to the application (for example, onthe MQGET call), the queue manager always pads with nulls to the defined lengthof the string.

Constants are available that define the lengths of byte string fields; see“Appendix B. MQSeries constants” on page 535.

MQCHAR - characterThe MQCHAR data type represents a single character. The coded character setidentifier of the character is that of the queue manager (see the CodedCharSetIdattribute on page 439). No special alignment is required.

Note: Application message data specified on the MQGET, MQPUT, and MQPUT1calls is described by the MQBYTE data type, not the MQCHAR data type.

MQCHARn - String of n charactersEach MQCHARn data type represents a string of n characters, where n can takeone of the following values:

4, 8, 12, 16, 20, 28, 32, 48, 64, 128, or 256

Each character is described by the MQCHAR data type. No special alignment isrequired.

If the data in the string is shorter than the defined length of the string, the datamust be padded with blanks to fill the string. In some cases a null character can beused to end the string prematurely, instead of padding with blanks; the nullcharacter and characters following it are treated as blanks, up to the defined lengthof the string. The places where a null can be used are identified in the call anddata type descriptions.

When the queue manager returns character strings to the application (for example,on the MQGET call), the queue manager always pads with blanks to the definedlength of the string; the queue manager does not use the null character to delimitthe string.

Constants are available that define the lengths of character string fields; see“Appendix B. MQSeries constants” on page 535.

MQHCONN - Connection handleThe MQHCONN data type represents a connection handle, that is, the connectionto a particular queue manager. A connection handle must be aligned on its naturalboundary.

Note: Applications must test variables of this type for equality only.

MQHOBJ - Object handleThe MQHOBJ data type represents an object handle that gives access to an object.An object handle must be aligned on its natural boundary.

Note: Applications must test variables of this type for equality only.

Elementary data types


MQLONG - Long integerThe MQLONG data type is a 32-bit signed binary integer that can take any valuein the range −2 147 483 648 through +2 147 483 647, unless otherwise restrictedby the context. For COBOL, the valid range is limited to −999 999 999 through+999 999 999. An MQLONG must be aligned on its natural boundary.

Elementary data type s - C programming languageTable 8. Elementary data types in C

Data type Representation

MQBYTE typedef unsigned char MQBYTE;

MQBYTE16 typedef MQBYTE MQBYTE16[16];





MQCHAR typedef char MQCHAR;

MQCHAR4 typedef MQCHAR MQCHAR4[4];











MQHCONN typedef MQLONG MQHCONN;

MQHOBJ typedef MQLONG MQHOBJ;

MQLONG typedef long MQLONG;

MQPTR typedef void MQPOINTER MQPTR;

PMQLONG typedef MQLONG MQPOINTER PMQLONG;

PMQVOID typedef void MQPOINTER PMQVOID;

See “Data types” on page 15 for a description of the MQPOINTER macro variable.


Chapter 1. Elementary data types 7

Elementary data types - COBOL programming languageTable 9. Elementary data types in COBOL


MQBYTE PIC X

MQBYTE16 PIC X(16)

MQBYTE24 PIC X(24)

MQBYTE32 PIC X(32)

MQBYTE40 PIC X(40)

MQBYTE64 PIC X(64)

MQCHAR PIC X

MQCHAR4 PIC X(4)

MQCHAR8 PIC X(8)

MQCHAR12 PIC X(12)

MQCHAR16 PIC X(16)

MQCHAR20 PIC X(20)

MQCHAR28 PIC X(28)

MQCHAR32 PIC X(32)

MQCHAR48 PIC X(48)

MQCHAR64 PIC X(64)

MQCHAR128 PIC X(128)

MQCHAR256 PIC X(256)

MQHCONN PIC S9(9) BINARY

MQHOBJ PIC S9(9) BINARY

MQLONG PIC S9(9) BINARY

MQPTR POINTER

PMQLONG POINTER

Elementary data types - PL/I language (AIX, OS/2, OS/390,VSE/ESA, and Windows NT only)

Table 10. Elementary data types in PL/I


MQBYTE char(1)

MQBYTE16 char(16)

MQBYTE24 char(24)

MQBYTE32 char(32)

MQBYTE40 char(40)

MQBYTE64 char(64)



Table 10. Elementary data types in PL/I (continued)


MQCHAR char(1)

MQCHAR4 char(4)

MQCHAR8 char(8)

MQCHAR12 char(12)

MQCHAR16 char(16)

MQCHAR20 char(20)

MQCHAR28 char(28)

MQCHAR32 char(32)

MQCHAR48 char(48)

MQCHAR64 char(64)

MQCHAR128 char(128)

MQCHAR256 char(256)

MQHCONN fixed bin(31)

MQHOBJ fixed bin(31)

MQLONG fixed bin(31)

PMQLONG pointer

Elementary data types - System/390 Assembler (OS/390 only)Table 11. Elementary data types in System/390 assembler


MQBYTE DS XL1

MQBYTE16 DS XL16

MQBYTE24 DS XL24

MQBYTE32 DS XL32

MQBYTE40 DS XL40

MQBYTE64 DS XL64

MQCHAR DS CL1

MQCHAR4 DS CL4

MQCHAR8 DS CL8

MQCHAR12 DS CL12

MQCHAR16 DS CL16

MQCHAR20 DS CL20

MQCHAR28 DS CL28

MQCHAR32 DS CL32

MQCHAR48 DS CL48



Table 11. Elementary data types in System/390 assembler (continued)


MQCHAR64 DS CL64

MQCHAR128 DS CL128

MQCHAR256 DS CL256

MQHCONN DS F

MQHOBJ DS F

MQLONG DS F

PMQLONG DS F

Elementary data types - TAL programming language (TandemNonStop Kernel only)

Table 12. Elementary data types in TAL

Data Type Representation

MQBYTE STRING

MQBYTE24 BEGIN STRING BYTE [0:23];END

MQBYTE32 BEGIN STRING BYTE [0:31];END

MQCHAR STRING

MQCHAR4 BEGIN STRING BYTE [0:3];END

MQCHAR8 BEGIN STRING BYTE [0:7]; END








MQHCONN INT(32)

MQHOBJ INT(32)

MQLONG INT(32)

Elementary data types - Visual Basic (Windows 3.1, Windows95, Windows 98, and Windows NT)

Table 13. Elementary data types in Visual Basic


MQBYTE String*1

MQBYTE24 String*24

MQBYTE32 String*32

MQCHAR String*1

MQCHAR4 String*4

MQCHAR8 String*8



Table 13. Elementary data types in Visual Basic (continued)


MQCHAR12 String*12

MQCHAR28 String*28

MQCHAR32 String*32

MQCHAR48 String*48

MQCHAR64 String*64

MQCHAR128 String*128

MQCHAR256 String*256

MQHCONN Long

MQHOBJ Long

MQLONG Long



Chapter 2. Structure data types – programmingconsiderations

This chapter describes:v The conventions used in the description of the data type structures used by the

MQI.v Some of the programming considerations you need to consider when using the

data type structures in the supported programming languages.

The structure data types used by the MQI are:v MQBO – Begin optionsv MQCNO – Connect optionsv MQGMO – Get-message optionsv MQMD – Message descriptorv MQMDE – Message descriptor extensionv MQOD – Object descriptorv MQOR – Object recordv MQPMO – Put-message optionsv MQPMR – Put message recordv MQRMH – Message reference headerv MQRR – Response record

The MQI also uses the following structure data types, which are included in thischapter for completeness, but they are not part of the application programminginterface.v MQCIH – CICS bridge headerv MQDH – Distribution headerv MQDLH – Dead-letter (undelivered-message) headerv MQIIH – IMS™ bridge headerv MQTM – Trigger messagev MQTMC2 – Trigger message (character format 2)v MQWIH – Work Information headerv MQXQH – Transmission queue header

Note: The MQDXP – data conversion exit parameter structure is in “Appendix F.Data conversion” on page 607, together with the associated data conversioncalls.

Conventions used in the descriptions of data typesFor each structure data type, this chapter gives a description of its usage, in a formthat is independent of the programming language. This is followed by typicaldeclarations in each of the supported programming languages.

The description of each structure data type contains the following sections:

Structure nameThe name of the structure, followed by a brief description of the purposeof the structure.

Fields For each field, the name is followed by its elementary data type inparentheses ( ); for example:


Version (MQLONG)

There is also a description of the purpose of the field, together with a listof any values that the field can take. Names of constants are shown inuppercase; for example, MQGMO_STRUC_ID. A set of constants havingthe same prefix is shown using the * character, for example: MQIA_*.

In the descriptions of the fields, the following terms are used:

input You supply information in the field when you make a call.

outputThe queue manager returns information in the field when the callcompletes or fails.

input/outputYou supply information in the field when you make a call, and thequeue manager changes the information when the call completesor fails.

Initial valuesA table showing the initial values for each field in the data definition filessupplied with the MQI.

C declarationTypical declaration of the structure in C.

COBOL declarationTypical declaration of the structure in COBOL.

PL/I declarationTypical declaration of the structure in PL/I2.

System/390 assembler-language declarationTypical declaration of the structure in System/3902 assembler language.

Visual Basic declarationTypical declaration of the structure in Visual basic.

Language considerationsThis section outlines the requirements for data types in the following programminglanguages:v C – see “Using the data types in the C programming language”v COBOL – see “Using the data types in the COBOL programming language” on

page 17v PL/I – see “Using the data types in the PL/I programming language” on

page 20v Assembler/390 – see “Using the data types in the System/390 Assembler

programming language” on page 22v Visual Basic – see “Using the data types in the Visual Basic programming

language” on page 24

Using the data types in the C programming languageThis section contains information to help you use the MQI from the Cprogramming language.

2. PL/I and assembler are not sensitive to case, so the names of calls, structure fields, and constants can be coded in lowercase,uppercase, or mixed case.

Structure data types


Header filesHeader files are provided as part of the definition of the message queue interface,to assist with the writing of C application programs that use message queuing.These header files are summarized in Table 14.

Table 14. C header file

Filename Contents

CMQC Function prototypes, data types, and named constants for the main MQI

CMQXC Function prototypes, data types, and named constants for the data-conversion exit

To improve the portability of applications, it is recommended that the name of theheader file should be coded in lowercase on the #include preprocessor directive:#include "cmqc.h"

FunctionsParameters that are input-only and of type MQHCONN, MQHOBJ, or MQLONGare passed by value; for all other parameters, the address of the parameter is passedby value.

Not all parameters that are passed by address need to be specified every time afunction is invoked. Where a particular parameter is not required, a null pointercan be specified as the parameter on the function invocation, in place of theaddress of the parameter data. Parameters for which this is possible are identifiedin the call descriptions.

No parameter is returned as the value of the function; in C terminology, this meansthat all functions return void.

The attributes of the function are defined by the MQENTRY macro variable; thevalue of this macro variable depends on the environment.

Parameters with undefined data typeThe MQGET, MQPUT, and MQPUT1 functions each have one parameter that hasan undefined data type, namely the Buffer parameter. This parameter is used tosend and receive the application’s message data.

Parameters of this sort are shown in the C examples as arrays of MQBYTE. It isperfectly valid to declare the parameters in this way, but it is usually moreconvenient to declare them as the particular structure which describes the layout ofthe data in the message. The actual function parameter is declared as apointer-to-void, and so the address of any sort of data can be specified as theparameter on the function invocation.

Data typesAll data types are defined by means of the C typedef statement. For each datatype, the corresponding pointer data type is also defined. The name of the pointerdata type is the name of the elementary or structure data type prefixed with theletter “P” to denote a pointer. The attributes of the pointer are defined by theMQPOINTER macro variable; the value of this macro variable depends on theenvironment. The following illustrates how pointer data types are declared:#define MQPOINTER * /* depends on environment */...typedef MQLONG MQPOINTER PMQLONG; /* pointer to MQLONG */typedef MQMD MQPOINTER PMQMD; /* pointer to MQMD */

Language considerations

Chapter 2. Structure data types – programming considerations 15

Manipulating binary stringsStrings of binary data are declared as one of the MQBYTEn data types. Wheneverfields of this type are copied, compared, or set, the C functions memcpy, memcmp,or memset should be used; for example:#include #include "cmqc.h"

MQMD MyMsgDesc;

memcpy(MyMsgDesc.MsgId, /* set "MsgId" field to nulls */MQMI_NONE, /* ...using named constant */sizeof(MyMsgDesc.MsgId));

memset(MyMsgDesc.CorrelId, /* set "CorrelId" field to nulls */0x00, /* ...using a different method */sizeof(MQBYTE24));

Do not use the string functions strcpy, strcmp, strncpy, or strncmp, because thesedo not work correctly for data declared with the MQBYTEn data types.

Manipulating character stringsWhen the queue manager returns character data to the application, the queuemanager always pads the character data with blanks to the defined length of thefield; the queue manager does not return null-terminated strings. Therefore, whencopying, comparing, or concatenating such strings, the string functions strncpy,strncmp, or strncat should be used.

Do not use the string functions, which require the string to be terminated by a null(strcpy, strcmp, strcat). Also, do not use the function strlen to determine the lengthof the string; use instead the sizeof function to determine the length of the field.

Initial values for structuresThe header file CMQC defines various macro variables that may be used toprovide initial values for the message queuing structures when instances of thosestructures are declared. These macro variables have names of the form“MQXXX_DEFAULT”, where “MQXXX” represents the name of the structure. Theyare used in the following way:MQMD MyMsgDesc = {MQMD_DEFAULT};MQPMO MyPutOpts = {MQPMO_DEFAULT};

For some character fields (for example, the StrucId fields which occur in moststructures, or the Format field which occurs in MQMD), the MQI defines particularvalues that are valid. For each of the valid values, two macro variables areprovided:v One macro variable defines the value as a string whose length excluding the

implied null matches exactly the defined length of the field. For example, for theFormat field in MQMD the following macro variable is provided (the symbol “”represents a blank character):#define MQFMT_STRING "MQSTR"

Use this form with the memcpy and memcmp functions.v The other macro variable defines the value as an array of characters; the name of

this macro variable is the name of the string form suffixed with “_ARRAY”. Forexample:#define MQFMT_STRING_ARRAY 'M','Q','S','T','R','','',''



Use this form to initialize the field when an instance of the structure is declaredwith values different from those provided by the MQMD_DEFAULT macrovariable.3

Initial values for dynamic structuresWhen a variable number of instances of a structure is required, the instances areusually created in main storage obtained dynamically using the calloc or mallocfunctions. To initialize the fields in such structures, the following technique isrecommended:1. Declare an instance of the structure using the appropriate MQXXX_DEFAULT

macro variable to initialize the structure. This instance becomes the “model” forother instances:MQMD Model = {MQMD_DEFAULT}; /* declare model instance */

The static or auto keywords can be coded on the declaration in order to givethe model instance static or dynamic lifetime, as required.

2. Use the calloc or malloc functions to obtain storage for a dynamic instance ofthe structure:PMQMD Instance;Instance = malloc(sizeof(MQMD)); /* get storage for dynamic instance */

3. Use the memcpy function to copy the model instance to the dynamic instance:memcpy(Instance,&Model,sizeof(MQMD)); /* initialize dynamic instance */

Use from C++For the C++ programming language, the header files contain the followingadditional statements that are included only when a C++ compiler is used:#ifdef __cplusplusextern "C" {

#endif

/* rest of header file */

#ifdef __cplusplus}

#endif

Notational conventionsThe sections that follow show how the:v Calls should be invokedv Parameters should be declaredv Various data types should be declared

In a number of cases, parameters are arrays whose size is not fixed. For these, alowercase “n” is used to represent a numeric constant. When the declaration forthat parameter is coded, the “n” must be replaced by the numeric value required.

Using the data types in the COBOL programming languageThis section contains information to help you use the MQI from the COBOLprogramming language.

3. This is not always necessary; in some environments the string form of the value can be used in both situations. However, thearray form is recommended for declarations, since this is required for compatibility with the C++ programming language.


Chapter 2. Structure data types – programming considerations 17

COPY filesVarious COPY files are provided as part of the definition of the message queueinterface, to assist with the writing of COBOL application programs that usemessage queuing. There are two files containing the named constants, and twofiles for each of the structures.

Each structure is provided in two forms: a form with initial values, and a formwithout.v The structures with initial values can be used in the WORKING-STORAGE

SECTION of a COBOL program, and are contained in COPY files which havenames suffixed with the letter “V” (mnemonic for “Values”).

v The structures without initial values can be used in the LINKAGE SECTION ofa COBOL program, and are contained in COPY files which have names suffixedwith the letter “L” (mnemonic for “Linkage”).

The COPY files are summarized in Table 15. Note that not all of the files listed areavailable in all environments.

Table 15. COBOL COPY files

File name (with initial values) File name (without initial values) Contents

CMQBOV CMQBOL Begin options structure

CMQCIHV CMQCIHL CICS information header structure

CMQCNOV CMQCNOL Connect options structure

CMQDHV CMQDHL Distribution header structure

CMQDLHV CMQDLHL Dead-letter (undelivered-message) he

public.dhe.ibm.com · pl/i declaration ...........106 system/390 assembler declaration .....107 tal...

Documents