Micro Focus Visual COBOL 2.3 Update 1 for Eclipse (UNIX) > General Reference > Library Routines > Alphabetical List of Library Routines > CBL_NLS_READ_MSG

CBL_NLS_READ_MSG

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-params containing:

01 cblt-nls-msg-params          typedef.
  03 cblte-nmpb-set-number      cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-number          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-max-buffer-len  cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-actual-msg-len  cblt-x2-compx. 	*> pic x(n) comp-x.
  03 cblte-nmpb-flags           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      typedef.
  03 cblte-nmis-ins-count       cblt-x2-compx.  *> pic x(2) comp-x.
  03 cblte-nmis-ins-pointer     cblt-pointer.   *> usage pointer.
                                                *> Occurs depending on ins-count.

msg-buffer

Call prototype (see Key): pic x(n).

Picture: pic x(n).

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.