CBL_NLS_READ_MSG

Reads a message from a National Locale Support (NLS) message file.
Restriction: National Locale Support is only supported for native COBOL code.

Syntax:

call "CBL_NLS_READ_MSG" using     msg-file-handle
                                  full-msg-number
                                  msg-ins-struct
                                  msg-buffer
                        returning status-code

Parameters

msg-file-handle
Call prototype (see Key): cblt-x4-compx .
Picture: pic x(4).
full-msg-number
Group predefined as cblt-nls-msg-number-pair containing:
01 cblt-nls-msg-number-pair.
  03 cblte-nmnp-set-number      cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmnp-number          cblt-x2-compx. 	*> pic x(2) comp-x.
  
msg-ins-struct
Group predefined as cblt-nls-msg-ins-struct containing:
01 cblt-nls-msg-ins-struct.
  03 cblte-nmis-ins-count       cblt-x2-compx.  *> pic x(2) comp-x.
  03 cblte-nmis-ins-pointer     cblt-pointer.   *> usage pointer occurs n times
                                                *> depending on cblte-nmis-ins-count.
msg-buffer
Group predefined as cblt-nls-msg-buffer containing:
01 cblt-nls-msg-buffer.
   03 cblte-nmb-buf-len   cblt-x2-compx. 	*> pic x(2) comp-x.
   03 cblte-nmb-buf-text  cblt-x2-compx. 	*> pic x(n) occurs n times 
                                          *> depending on cblte-nmb-buff-len.
status-code
See Library Routines - Key.

On Entry:

msg-file-handle
The identifying handle of the message file to fetch the message from.
cblte-nmnp-set-number
The set in the message file to fetch the message from.
cblte-nmnp-number
The message number in the message set to fetch the message from.
cblte-nmis-ins-count
The number of portions of text to insert in the message.
cblte-nmis-ins-pointer
A pointer to a null-terminated portion of text to insert in the message.
cblte-nmb-buff-len
The length of msg-buff-text.

On Exit:

cblte-nmb-buff-text
The returned text (null-terminated).
status-code
Indicates whether the routine was successful:
0 Success
40 NLS module not initialized
401 Message set not found
402 Message not found in set
403 Message too long for message text buffer
404 Invalid msg-file-handle
If status-code contains a value other than these, it is the number of a run-time error message.

Comments:

In each message catalog, messages can be divided into sets. Each message in a set has an identifying message number. Message catalogs are explained in more detail in the section Writing NLS Message Files in the chapter Internationalization Support in the book Program Development.

This routine also enables you to insert portions of text in a message fetched from the message catalog, replacing any %s formatting sequences in the original message. There must not be more %s formatting sequences than cblte-nmis-ins-count.

The inserted portions of text can be inserted in the order appropriate to the rules of the grammar for the national language. This is achieved using the %n$s formatting syntax, where n is the nth cblte-nmis-ins-pointer. The value of n must not exceed cblte-nmis-ins-count.