Convenzioni di elaborazione

Quando si converte un formato integrato, il gestore code segue le convenzioni di elaborazione descritte.

Anche le uscite scritte dall'utente devono seguire queste convenzioni, anche se non vengono applicate dal gestore code. I formati integrati convertiti dal gestore code sono:
  • MMQFMT_ADMIN
  • MQFMT_CICS® (solo z/OS® )
  • MQFMT_COMMAND_1
  • MQFMT_COMMAND_2
  • MQFMT_DEAD_LETTER_HEADER
  • INTESTAZIONE_DIST_MQFM
  • MQFMT_EVENT versione 1
  • MQFMT_EVENT versione 2
  • IMS MQFMT
  • MQFMT_IMS_VAR_STRING
  • MQFMT_MD_EXTENSIONE
  • MQFMT_PCF
  • MQFMT_REF_MSG_HEADER
  • MQFMT_RF_HEADER
  • MQFMT_RF_HEADER_2
  • MQFMT_STRING
  • MQFMT_TRIGGER
  • MQFMT_WORK_INFO_HEADER (solo z/OS )
  • MQFMT_XMIT_Q_HEADER
  1. Se il messaggio si espande durante la conversione e supera la dimensione del parametro Buffer , viene eseguito quanto segue:
    • Se l'opzione MQGMO_ACCEPT_TRUNCATED_MSG non è stata specificata, il messaggio viene restituito non convertito, con codice di completamento MQCC_WARNING e codice motivo MQRC_CONVERTED_MSG_TOO_BIG.
    • Se l'opzione MQGMO_ACCEPT_TRUNCATED_MSG è stata specificata, il messaggio viene troncato, il codice di completamento è impostato su MQCC_WARNING, il codice di errore è impostato su MQRC_TRUNCATED_MSG_ACCEPTED e l'elaborazione della conversione continua.
  2. Se si verifica un troncamento (prima o durante la conversione), il numero di byte validi restituiti nel parametro Buffer può essere inferiore alla lunghezza del buffer.

    Ciò può verificarsi, ad esempio, se un numero intero a 4 byte o un carattere DBCS si trova alla fine del buffer. L'elemento incompleto delle informazioni non viene convertito e i byte nel messaggio restituito non contengono informazioni valide. Ciò può verificarsi anche se un messaggio troncato prima della conversione si riduce durante la conversione.

    Se il numero di byte validi restituiti è inferiore alla lunghezza del buffer, i byte inutilizzati alla fine del buffer vengono impostati su valori null.

  3. Se una schiera o una stringa si trova a cavallo della fine del buffer, viene convertita la maggior parte dei dati possibile; non viene convertito solo il particolare elemento della schiera o il carattere DBCS incompleto; vengono convertiti i caratteri o gli elementi della schiera precedenti.
  4. Se si verifica il troncamento (prima o durante la conversione), la lunghezza restituita per il parametro DataLength è la lunghezza del messaggio non convertito prima del troncamento.
  5. Quando le stringhe vengono convertite tra serie di caratteri a byte singolo (SBCS), serie di caratteri a byte doppio (DBCS) o serie di caratteri a più byte (MBCS), le stringhe possono espandersi o contrarsi.
    • Nei formati PCF MQFMT_ADMIN, MQFMT_EVENT e MQFMT_PCF, le stringhe nelle strutture MQCFST e MQCFSL si espandono o si contraggono in base alle necessità per adattare la stringa dopo la conversione.

      Per la struttura dell'elenco di stringhe MQCFSL, le stringhe nell'elenco potrebbero espandersi o contrarsi in base a quantità differenti. Se ciò si verifica, il gestore code riempirebbe le stringhe più corte con spazi vuoti per renderle della stessa lunghezza della stringa più lunga dopo la conversione.

    • Nel formato MQFMT_REF_MSG_HEADER, le stringhe indirizzate dai campi SrcEnvOffset, SrcNameOffset, DestEnvOffsete DestNameOffset si espandono o si contraggono in base alle necessità per adattare le stringhe dopo la conversione.
    • Nel formato MQFMT_RF_HEADER, il campo NameValueString si espande o si contrae come necessario per adattare le coppie nome / valore dopo la conversione.
    • Nelle strutture con dimensioni di campo fisse, il gestore code consente alle stringhe di espandersi o di contrarsi all'interno dei relativi campi fissi, a condizione che non vengano perse informazioni significative. A questo proposito, gli spazi vuoti finali e i caratteri che seguono il primo carattere null nel campo vengono trattati come non significativi.
      • Se la stringa si espande, ma solo i caratteri non significativi devono essere scartati per contenere la stringa convertita nel campo, la conversione ha esito positivo e la chiamata viene completata con MQCC_OK e codice motivo MQRC_NONE (supponendo che non vi siano altri errori).
      • Se la stringa si espande, ma la stringa convertita richiede l'eliminazione di caratteri significativi per poter essere inserita nel campo, il messaggio viene restituito non convertito e la chiamata viene completata con MQCC_WARNING e codice motivo MQRC_CONVERTED_STRING_TOO_BIG.
        Nota: in questo caso il codice di errore MQRC_CONVERTED_STRING_TOO_BIG indica se è stata specificata o meno l'opzione MQGMO_ACCEPT_TRUNCATED_MSG.
      • Se la stringa si contrae, il gestore code riempiendo la stringa con spazi vuoti fino alla lunghezza del campo.
  6. Per i messaggi costituiti da una o più strutture di intestazione MQ seguite da dati utente, è possibile che una o più strutture di intestazione vengano convertite, mentre il resto del messaggio non lo è. Tuttavia, (con due eccezioni) i campi CodedCharSetId e Encoding in ogni struttura di intestazione indicano sempre correttamente la serie di caratteri e la codifica dei dati che seguono la struttura di intestazione.

    Le due eccezioni sono le strutture MQCIH e MQIIH, in cui i valori nei campi CodedCharSetId e Encoding in tali strutture non sono significativi. Per tali strutture, i dati che seguono la struttura si trovano nella stessa serie di caratteri e nella stessa codifica della struttura MQCIH o MQIIH.

  7. Se i campi CodedCharSetId o Encoding nelle informazioni di controllo del messaggio richiamato o nel parametro MsgDesc , specificano valori non definiti o non supportati, il gestore code potrebbe ignorare l'errore se non è necessario utilizzare il valore non definito o non supportato nella conversione del messaggio.

    Ad esempio, se il campo Encoding nel messaggio specifica una codifica a virgola mobile non supportata, ma il messaggio contiene solo dati interi o contiene dati a virgola mobile che non richiedono la conversione (poiché le codifiche a virgola mobile di origine e di destinazione sono identiche), l'errore potrebbe non essere diagnosticato.

    Se l'errore viene diagnosticato, il messaggio viene restituito non convertito, con codice di completamento MQCC_WARNING e uno dei codici di errore MQRC_SOURCE_ * _ERROR o MQRC_TARGET_ * _ERROR (come appropriato); i campi CodedCharSetId e Encoding del parametro MsgDesc sono impostati sui valori nelle informazioni di controllo nel messaggio.

    Se l'errore non viene diagnosticato e la conversione viene completata correttamente, i valori restituiti nei campi CodedCharSetId e Encoding nel parametro MsgDesc sono quelli specificati dall'applicazione che emette la chiamata MQGET.

  8. In tutti i casi, se il messaggio viene restituito all'applicazione non convertita, il codice di completamento viene impostato su MQCC_WARNING e i campi CodedCharSetId e Encoding nel parametro MsgDesc vengono impostati sui valori appropriati per i dati non convertiti. Questa operazione viene eseguita anche per MQFMT_NONE.

    Il parametro Reason è impostato su un codice che indica il motivo per cui non è stato possibile eseguire la conversione, a meno che non sia stato necessario troncare anche il messaggio; i codici di errore relativi al troncamento hanno la precedenza sui codici di errore relativi alla conversione. (Per determinare se un messaggio troncato è stato convertito, controllare i valori restituiti nei campi CodedCharSetId e Encoding nel parametro MsgDesc .)

    Quando viene diagnosticato un errore, viene restituito un codice di errore specifico oppure il codice di errore generale MQRC_NOT_CONVERTED. Il codice motivo restituito dipende dalle capacità diagnostiche del servizio di conversione dati sottostante.

  9. Se viene restituito il codice di completamento MQCC_WARNING e più di un codice di errore è rilevante, l'ordine di precedenza è il seguente:
    1. I seguenti motivi hanno la precedenza su tutti gli altri; solo uno dei motivi in questo gruppo può sorgere:
      • MQRC_SIGNAL_REQUEST_ACCEPTED
      • MQRC_TRUNCATED_MSG_ACCEPTED
    2. L'ordine di precedenza all'interno dei codici di errore rimanenti non è definito.
  10. Al completamento della chiamata MQGET:
    • Il seguente codice di errore indica che il messaggio è stato convertito correttamente:
      • MQRC_NONE
    • I seguenti codici di errore indicano che il messaggio potrebbe essere stato convertito correttamente (controllare i campi CodedCharSetId e Encoding nel parametro MsgDesc per scoprirlo):
      • MQRC_MSG_MARKED_BROWSE_CO_OP
      • MQRC_TRUNCATED_MSG_ACCEPTED
    • Tutti gli altri codici di errore indicano che il messaggio non è stato convertito.

    La seguente elaborazione è specifica per i formati integrati; non si applica ai formati definiti dall'utente:

  11. Ad eccezione dei formati seguenti:
    • MMQFMT_ADMIN
    • MQFMT_COMMAND_1
    • MQFMT_COMMAND_2
    • EVENTO MQFMT
    • MQFMT_IMS_VAR_STRING
    • MQFMT_PCF
    • MQFMT_STRING
    nessuno dei formati integrati può essere convertito da o in serie di caratteri che non dispongono di caratteri SBCS per i caratteri validi nei nomi delle code. Se viene effettuato un tentativo di eseguire tale conversione, il messaggio viene restituito non convertito, con il codice di completamento MQCC_WARNING e il codice motivo MQRC_SOURCE_CCSID_ERROR o MQRC_TARGET_CCSID_ERROR, come appropriato.

    La serie di caratteri Unicode UCS-2 rappresenta un esempio di serie di caratteri che non dispone di caratteri SBCS per i caratteri validi nei nomi coda.

  12. Se i dati del messaggio per un formato integrato vengono troncati, i campi all'interno del messaggio che contengono lunghezze di stringhe o conteggi di elementi o strutture, non vengono modificati per riflettere la lunghezza dei dati effettivamente restituiti all'applicazione; i valori restituiti per tali campi all'interno dei dati del messaggio sono i valori applicabili al messaggio prima del troncamento.

    Quando si elaborano messaggi come ad esempio un messaggio MQFMT_ADMIN troncato, assicurarsi che l'applicazione non tenti di accedere ai dati oltre la fine dei dati restituiti.

  13. Se il nome del formato è MQFMT_DEAD_LETTER_HEADER, i dati del messaggio iniziano con una struttura MQDLH, possibilmente seguita da zero o più byte di dati del messaggio dell'applicazione. Il formato, la serie di caratteri e la codifica dei dati del messaggio dell'applicazione sono definiti dai campi Format, CodedCharSetIde Encoding nella struttura MQDLH all'inizio del messaggio. Poiché la struttura MQDLH e i dati del messaggio dell'applicazione possono avere diverse serie di caratteri e codifiche, una, un'altra o entrambe le strutture MQDLH e i dati del messaggio dell'applicazione potrebbero richiedere la conversione.

    Il gestore code converte prima la struttura MQDLH, come necessario. Se la conversione ha esito positivo o se la struttura MQDLH non richiede la conversione, il gestore code controlla i campi CodedCharSetId e Encoding nella struttura MQDLH per verificare se è richiesta la conversione dei dati del messaggio dell'applicazione. Se la conversione è richiesta, il gestore code richiama l'uscita scritta dall'utente con il nome fornito dal campo Format nella struttura MQDLH oppure esegue la conversione stessa (se Format è il nome di un formato integrato).

    Se la chiamata MQGET restituisce un codice di completamento MQCC_WARNING e il codice motivo è uno di quelli che indicano che la conversione non è stata eseguita correttamente, si applica una delle seguenti condizioni:
    • Non è possibile convertire la struttura MQDLH. In questo caso, anche i dati del messaggio dell'applicazione non saranno stati convertiti.
    • La struttura MQDLH è stata convertita, ma non i dati del messaggio dell'applicazione.
    L'applicazione può esaminare i valori restituiti nei campi CodedCharSetId e Encoding nel parametro MsgDesc e quelli nella struttura MQDLH, al fine di determinare quale dei precedenti si applica.
  14. Se il nome del formato è MQFMT_XMIT_Q_HEADER, i dati del messaggio iniziano con una struttura MQXQH, possibilmente seguita da zero o più byte di dati aggiuntivi. Questi dati aggiuntivi sono di solito i dati del messaggio dell'applicazione (che possono essere di lunghezza zero), ma possono essere presenti anche una o più ulteriori strutture di intestazione MQ , all'inizio dei dati aggiuntivi.

    La struttura MQXQH deve essere nella serie di caratteri e nella codifica del gestore code. Il formato, la serie di caratteri e la codifica dei dati che seguono la struttura MQXQH sono forniti dai campi Format, CodedCharSetIde Encoding nella struttura MQMD contenuta all'interno di MQXQH. Per ogni struttura di intestazione MQ successiva presente, i campi Format, CodedCharSetIde Encoding nella struttura descrivono i dati che seguono tale struttura; tali dati sono un'altra struttura di intestazioni MQ o i dati del messaggio dell'applicazione.

    Se l'opzione MQGMO_CONVERT viene specificata per un messaggio MQFMT_XMIT_Q_HEADER, i dati del messaggio dell'applicazione e alcune delle strutture dell'intestazione MQ vengono convertite, ma i dati nella struttura MQXQH non sono. Al ritorno dalla chiamata MQGET, quindi:
    • I valori dei campi Format, CodedCharSetIde Encoding nel parametro MsgDesc descrivono i dati nella struttura di MQXQH e non i dati del messaggio dell'applicazione; i valori, quindi, non sono uguali a quelli specificati dall'applicazione che ha emesso la chiamata MQGET.

      L'effetto di questa operazione è che un'applicazione che riceve ripetutamente i messaggi da una coda di trasmissione con l'opzione MQGMO_CONVERT specificata deve reimpostare i campi CodedCharSetId e Encoding nel parametro MsgDesc sui valori richiesti per i dati del messaggio dell'applicazione, prima di ogni chiamata MQGET.

    • I valori dei campi Format, CodedCharSetIde Encoding presenti nell'ultima struttura di intestazioni MQ descrivono i dati del messaggio dell'applicazione. Se non sono presenti altre strutture di intestazione MQ , i dati del messaggio dell'applicazione vengono descritti da questi campi nella struttura MQMD all'interno della struttura MQXQH. Se la conversione ha esito positivo, i valori saranno gli stessi specificati nel parametro MsgDesc dall'applicazione che ha emesso la chiamata MQGET.

    Se il messaggio è un messaggio elenco di distribuzione, la struttura MQXQH è seguita da una struttura MQDH (più i relativi array di record MQOR e MQPMR), che a sua volta potrebbe essere seguita da zero o più ulteriori strutture di intestazione MQ e zero o più byte di dati del messaggio dell'applicazione. Come la struttura MQXQH, la struttura MQDH deve essere nella serie di caratteri e nella codifica del gestore code e non viene convertita nella chiamata MQGET, anche se è specificata l'opzione MQGMO_CONVERT.

    L'elaborazione delle strutture MQXQH e MQDH descritte in precedenza è destinata principalmente all'utilizzo da parte degli agent del canale dei messaggi quando ricevono i messaggi dalle code di trasmissione.