MQMHBUF - Conversione dell'handle del messaggio in buffer

La chiamata MQMHBUF converte un gestore messaggi in un buffer ed è l'inverso della chiamata MQBUFMH.

Sintassi

MQMHBUF (Hconn, Hmsg, MsgHBufOpts, Name, MsgDesc, BufferLength, Buffer, DataLength, CompCode, Reason )

Parametri

Hconn

Tipo: MQHCONN - input

Questo handle rappresenta la connessione al gestore code. Il valore di Hconn deve corrispondere all'handle di connessione utilizzato per creare l'handle del messaggio specificato nel parametro Hmsg .

Se l'handle del messaggio è stato creato utilizzando MQHC_UNASSOCIATED_HCONN, è necessario stabilire una connessione valida sul thread che elimina l'handle del messaggio. Se non viene stabilita una connessione valida, la chiamata ha esito negativo con MQRC_CONNECTION_BROKEN.

Messaggio

Tipo: MQHMSG - input

Questo è l'handle del messaggio per cui è richiesto un buffer. Il valore è stato restituito da una precedente chiamata MQCRTMH.

MsgHBufOpts

Tipo: MQMHBO - input

La struttura MQMHBO consente alle applicazioni di specificare le opzioni che controllano la modalità di produzione dei buffer dagli handle dei messaggi.

Per i dettagli, consultare MQMHBO - Gestione dei messaggi per le opzioni del buffer .

Nome

Tipo: MQCHARV - input

Il nome della proprietà o delle proprietà da inserire nel buffer.

Se non è possibile trovare alcuna proprietà corrispondente al nome, la chiamata non riesce con MQRC_PROPERTY_NOT_AVAILABLE.

È possibile utilizzare un carattere jolly per inserire più di una proprietà nel buffer. A tale scopo, utilizzare il carattere jolly '%' alla fine del nome della proprietà. Questo carattere jolly corrisponde a zero o più caratteri, incluso il carattere '.' carattere.

Nel linguaggio di programmazione C, le seguenti variabili macro sono definite per analizzare tutte le proprietà e tutte le proprietà che iniziano con 'usr':

MQPROP_INQUIRE_TUTTI: Inserire tutte le proprietà del messaggio nel buffer
MQPROP_INQUIRE_ALL_USR: Inserire tutte le proprietà del messaggio che iniziano con i caratteri 'usr.' nel buffer.

Consultare Nomi proprietà e Limitazioni nome proprietà per ulteriori informazioni sull'utilizzo dei nomi proprietà.

MsgDesc

Tipo: MQMD - input/output

La struttura MsgDesc descrive il contenuto dell'area buffer.

In fase di output, i campi Encoding, CodedCharSetId e Format sono impostati per descrivere correttamente la codifica, l'identificativo della serie di caratteri e il formato dei dati nell'area di buffer come scritto dalla chiamata.

I dati in questa struttura sono nella serie di caratteri e nella codifica dell'applicazione.

BufferLength

Tipo: MQLONG - input

BufferLength è la lunghezza dell'area Buffer, in byte.

Memorizza nel buffer

Tipo: MQBYTExBufferLength - uscita

Buffer definisce l'area che deve contenere le proprietà del messaggio. È necessario allineare il buffer su un limite di 4 byte.

Se BufferLength è inferiore alla lunghezza richiesta per memorizzare le proprietà in Buffer, MQMHBUF non riesce con MQRC_PROPERTY_VALUE_TOO_BIG.

Il contenuto del buffer può cambiare anche se la chiamata ha esito negativo.

DataLength

Tipo: MQLONG - output

DataLength è la lunghezza, in byte, delle proprietà restituite nel buffer. Se il valore è zero, nessuna proprietà corrisponde al valore fornito in Name e la chiamata ha esito negativo con codice motivo MQRC_PROPERTY_NOT_AVAILABLE.

Se BufferLength è inferiore alla lunghezza richiesta per memorizzare le proprietà nel buffer, la chiamata MQMHBUF ha esito negativo con MQRC_PROPERTY_VALUE_TOO_BIG, ma viene ancora immesso un valore in DataLength. Ciò consente all'applicazione di determinare la dimensione del buffer richiesto per contenere le proprietà e quindi emettere nuovamente la chiamata con il BufferLengthrichiesto.

CompCode

Tipo: MQLONG - output

Il codice di completamento; è uno dei seguenti:

MQCC_OK: Completamento con esito positivo.
MQCC_NON RIUSCITO: Chiamata fallita.

Motivo

Tipo: MQLONG - output

Il codice di errore che qualifica CompCode.

Se CompCode è MQCC_OK:

MQRC_NONE: (0, X'000 ') Nessun motivo per segnalare.

Se CompCode è MQCC_FAILED:

MQRC_ADAPTER_NON_DISPONIBILE: (2204, X'089C') Adattatore non disponibile.
MQRC_ADAPTER_SERV_LOAD_ERROR: (2130, X'852 ') Impossibile caricare il modulo di servizio adattatore.
MQRC_ASID_MISMATCH: (2157, X'86D') Gli ASID primari e domestici differiscono.
ERRORE MQRC_MHBO_: (2501, X'095C') L'handle del messaggio alla struttura delle opzioni del buffer non è valido.
ERRORE MQRC_BUFFER_: (2004, X'07D4') Parametro del buffer non valido.
ERRORE MQRC_BUFFER_LENGTH: (2005, X'07D5') Il parametro della lunghezza del buffer non è valido.
MQRC_CALL_IN_PROVERDE: (2219, X'08AB') Chiamata MQI inserita prima del completamento della chiamata precedente.
MQRC_CONNESSIONE_INTERROTTA: (2009, X'07D9') Connessione al gestore di code persa.
ERRORE MQRC_DATA_LENGTH: (2010, X'07DA') Parametro lunghezza dati non valido.
ERRORE MQRC_HMSG_: (2460, X'099C') L'handle del messaggio non è valido.
ERRORE MQRC_MD: (2026, X'07EA') Il descrittore del messaggio non è valido.
MQRC_MSG_HANDLE_IN_USE: (2499, X'09C3') Maniglia del messaggio già utilizzata.
ERRORE MQRC_OPTIONS_: (2046, X'07FE') Opzioni non valide o non coerenti.
ERRORE MQRC_PROPERTY_NAME_: (2442, X'098A') Il nome della proprietà non è valido.
PROPRIETÀ_MQRC_NON_DISPONIBILE: (2471, X'09A7') Proprietà non disponibile.
MQRC_PROPERTY_VALUE_TOO_BIG: (2469, X'09A5') Il valore BufferLength è troppo piccolo per contenere le proprietà specificate.
ERRORE MQRC_UNEXPECTED_: (2195, X'893 ') Si è verificato un errore non previsto.

Per informazioni dettagliate su questi codici, vedere Messaggi e codici di errore.

Richiamo C

MQMHBUF (Hconn, Hmsg, &MsgHBufOpts, &Name, &MsgDesc, BufferLength, Buffer,
         &DataLength, &CompCode, &Reason);

Dichiarare i parametri come segue:

MQHCONN Hconn;        /* Connection handle */
MQHMSG  Hmsg;         /* Message handle */
MQMHBO  MsgHBufOpts;  /* Options that control the action of MQMHBUF */
MQCHARV Name;         /* Property name */
MQMD    MsgDesc;      /* Message descriptor */
MQLONG  BufferLength; /* Length in bytes of the Buffer area */
MQBYTE  Buffer[n];    /* Area to contain the properties */
MQLONG  DataLength;   /* Length of the properties */
MQLONG  CompCode;     /* Completion code */
MQLONG  Reason;       /* Reason code qualifying CompCode */

Note d'utilizzo

MQMHBUF converte un handle del messaggio in un buffer.

È possibile utilizzarla con un'uscita API MQGET per accedere a determinate proprietà, utilizzando le API delle proprietà del messaggio, e quindi inoltrarle di nuovo in un buffer a un'applicazione progettata per utilizzare le intestazioni MQRFH2 piuttosto che gli handle del messaggio.

Questa chiamata è l'inverso della chiamata MQBUFMH, che è possibile utilizzare per analizzare le proprietà del messaggio da un buffer in un handle del messaggio.

Richiamo COBOL

     CALL 'MQMHBUF' USING HCONN, HMSG, MSGHBUFOPTS, NAME, MSGDESC,
                          BUFFERLENGTH, BUFFER, DATALENGTH, COMPCODE, REASON.

Dichiarare i parametri come segue:

**   Connection handle
 01  HCONN         PIC S9(9) BINARY.
**   Message handle
 01  HMSG          PIC S9(18) BINARY.
**   Options that control the action of MQMHBUF
 01  MSGHBUFOPTS.
     COPY CMQMHBOV.
**   Property name
 01  NAME
     COPY CMQCHRVV.
**   Message descriptor
 01  MSGDESC
     COPY CMQMDV.
**   Length in bytes of the Buffer area */
 01  BUFFERLENGTH  PIC S9(9) BINARY.
**   Area to contain the properties
 01  BUFFER        PIC X(n).
**   Length of the properties
 01  DATALENGTH    PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE      PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON        PIC S9(9) BINARY.

PL/I invocazione

call MQMHBUF (Hconn, Hmsg, MsgHBufOpts, Name, MsgDesc, BufferLength, Buffer,
DataLength, CompCode, Reason);

Dichiarare i parametri come segue:

dcl Hconn        fixed bin(31); /* Connection handle */
dcl Hmsg         fixed bin(63); /* Message handle */
dcl MsgHBufOpts  like MQMHBO;   /* Options that control the action of MQMHBUF */
dcl Name         like MQCHARV;  /* Property name */
dcl MsgDesc      like MQMD;     /* Message descriptor */
dcl BufferLength fixed bin(31); /* Length in bytes of the Buffer area */
dcl Buffer       char(n);       /* Area to contain the properties */
dcl DataLength   fixed bin(31); /* Length of the properties */
dcl CompCode     fixed bin(31); /* Completion code */
dcl Reason       fixed bin(31); /* Reason code qualifying CompCode */

Chiamata High Level Assembler

CALL MQMHBUF,(HCONN,HMSG,MSGHBUFOPTS,NAME,MSGDESC,BUFFERLENGTH,
                BUFFER,DATALENGTH,COMPCODE,REASON)

Dichiarare i parametri come segue:

HCONN        DS       F      Connection handle
HMSG         DS       D      Message handle
MSGHBUFOPTS  CMQMHBOA ,      Options that control the action of MQMHBUF
NAME         CMQCHRVA ,      Property name
MSGDESC      CMQMDA   ,      Message descriptor
BUFFERLENGTH DS       F      Length in bytes of the BUFFER area
BUFFER       DS       CL(n)  Area to contain the properties
DATALENGTH   DS       F      Length of the properties
COMPCODE     DS       F      Completion code
REASON       DS       F      Reason code qualifying COMPCODE