CBL_NLS_READ

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.