Digital

NAME

MESSAGE GROUP −  defines a named set of messages in a task group
 

SYNOPSIS

 MESSAGE GROUP <message-group-name>
      LANGUAGE IS <message-language-name> ;
      [ UUID <uuid-value> ; ]
 
      { <message-identifier>
           VALUE IS <message-number>
           CLASS IS <class-identifier>
           TEXT  IS <message-text>     ; }  [ ... ]
 
 END MESSAGE GROUP ;

PARAMETERS

       •message-group-name
 
An unqualified external identifier for the message group. The message group name must be unique within an application source directory. The message group name can be a maximum of 17 characters. The scope of the definition is the rest of the source file.
 
Multiple message group definitions with the same message group name are supported on the same TP system: one for each human language that the message group supports.

       •message-language-name
 
A restricted string literal giving the operating system name of a human language used for the message text.
 
      Language and Territory      Name
 
      Danish, Denmark             da_DK
      Dutch, Belgium              nl_BE
      Dutch, the Netherlands      nl_NL
      English, UK                 en_GB
      English, U.S.A              en_US
      Finnish, Finland            fi_FI
      French, Belgium             fr_BE
      French, Canada              fr_CA
      French, France              fr_FR
      French, Switzerland         fr_CH
      German, Switzerland         de_CH
      German, Germany             de_DE
      Icelandic, Iceland          is_IS
      Italian, Italy              it_IT
      Japanese, Japan             ja_JP
      Norwegian, Norway           no_NO
      Portuguese, Portugal        pt_PT
      Spanish, Spain              es_ES
      Swedish, Sweden             sv_SE
 
ENGLISH and JAPANESE are supported STDL human languages.

       •uuid-value
 
A restricted string literal giving the universal unique identifier (UUID) that uniquely identifies each message group definition within the message group definitions specified using the same message group language. If the message group languages for the message group definitions are different, the same UUID can be used for multiple message group definitions. This is how a user specifies different languages for the same message group.
 
If you do not specify a UUID value, the default value is zero.
 
Generation of UUIDs is the responsibility of the user. You can use the operating system-neutral interface to the UUID generation utility. For the operating system-neutral interface, see the DCE documentation of the uuidgen function.

       •message-identifier
 
An unqualified external identifier giving the name associated with a message within a message group definition. The scope of this identifier is the rest of the source file.
 
If the message group does not define a UUID, the message identifier must be unique within the message groups used by all tasks in a task group.
 
If the message group defines a UUID, the message identifier must be unique within the message group.

       •message-number
 
An integer literal that defines the nonzero, positive, integer value assigned to a message identifier.
 
If the message group does not define a UUID, the message number must be unique within the message groups used by tasks in a task group.
 
If the message group defines a UUID, the message number must be unique within the message group.

       •class-identifier
 
One of the standard, predefined exception classes, for example, ENV-EXECUTION-ERROR. See the exception man page for an explanation of exception classes and a list of STDL exception classes by type. 
 

       •message-text
 
A string literal that describes the error using the human language specified in the message group definition. This text is obtained by an executing task with the GET MESSAGE statement. Compose the message text using an execution character set suitable for the human language. For example, for ENGLISH, the string literal used for the message text must contain only characters from one of the Simple Latin, ISO Latin 1, ISO Latin 2, Kanji, or ISO UCS-2 execution character sets.
 
Compose the messages using standard and consistent terminology. Minimize extraneous words such as articles (for example, the, and, and an) and omit punctuation except for conveying explicit meaning.
 
Indicate variable arguments in the message text to be substituted by real arguments when getting the message text at run time. Separate the string literals by message parameters in the following format.
 
  %n
 
The value n is an integer literal from 1 to 9 with no space between the percent sign (%)  and the integer literal. The values of the message parameters indicate the order in which the corresponding real text is to be substituted at run time and the position of substitution in the message text.
 

DESCRIPTION

 
Each application-defined message must be defined in a message group associated with the task definition in which it is used.
 
The message group definition maps the text of the message to a message identifier or message number specified in a get message statement. The STDL compiler provides a way to generate a COBOL COPY file or a C include file for message group definitions.
 
Each message in the message group consists of:

oA message code as both:

-A message identifier, which is a symbolic name for a message code. 

-The integer value defined for the message identifier, which is the numeric value for the message code. The integer value can be exchanged between programs. 

oAn exception class that refers to one of the standard, predefined exception classes (see Table 22). 

oMessage text in the specified human language that can be exchanged between programs. 

Application-defined exceptions are defined as messages with an associated exception class. An STDL application can raise application-defined exceptions. The application-defined exceptions are available on each TP system that implements that message group.
 
When a task or a top-level processing procedure raises an exception using the message number or message identifier, ACMSxp software retrieves the class identifier for the message identifier. The initial type of exception raised (either nontransaction or transaction) is based on the class identifier.
 
Message groups with UUIDs are the exception code groups for exceptions raised by the application. If no UUID is specified in the message group definition, the application programmer must define unique exception codes.
 
The GET MESSAGE NUMBER statement retrieves the message text based on the message identifier. The message identifier is independent of the human language of the text describing the condition. The task can retrieve the message text with a GET MESSAGE statement. The same mechanism can be used to retrieve the message text within an exception handler.
 

Multiple Message Group Definitions

 
Use multiple message group definitions to support the same set of message identifiers in different languages. Use a different human language with the same message group name and message identifiers. Define multiple message group definitions as follows:

oUse the same message-group-name parameter. 

oSpecify a different human language for each human- language parameter. 

oIn each message group definition, define the same uuid-values, message-identifiers, message-numbers, and class-identifiers. 

oSupply different message-text parameters depending on the human language. 

 
Each message group is placed in a separate message catalog file and separate directory based on the human language supported.
 
The default language set by the end-user environment or the optional LANGUAGE IS phrase in the GET MESSAGE statement determines the message group definition to use by matching with the same language as specified in LANGUAGE IS in the message group definition. If the languages do not match, ACMSxp software generates an error.
 

Compilation Output

 
When you compile a message group definition to generate a COBOL COPY file or a C header file, one literal is defined for each message definition. Each literal is based on the message identifier:

oFor a COBOL COPY file, the STDL compiler converts any lowercase Latin characters in the message identifier to uppercase and replaces underscore (_)  characters with hyphen (-)  characters. 

oFor a C header file, the STDL compiler converts any uppercase Latin characters to lowercase, and replaces hyphen characters with underscore characters. 
 
Do not use kanji characters in identifiers if you plan to use C procedures.

RELATED INFORMATION

Syntax: get_message(1), task_definition(1), task_group(1) acmsxp_introduction(1)