get message(1) — Commands
Digital
NAME
GET MESSAGE − statement in a task that translates a message number or message identifier into message text
SYNOPSIS
[<label-name>:] GET MESSAGE NUMBER
{ <message-identifier> | <message-number> }
[ IN { <message-group-uuid> | <message-group-name> } ]
[ SOURCE IS { APPLICATION | SYSTEM | <source-field> } ]
[ LANGUAGE IS <human-language> ]
[ LENGTH IS <length-field> ]
[ USING <workspace-field> [ ,... ] ] ;
INTO <message-text-field> ;
PARAMETERS
•label-name
An internal unqualified identifier associated with the statement, for use in flow control operations.
•message-identifier
An external identifier associated with the message number, class identifier, and message text in a message group definition associated with this task definition. Use either the message identifier or the message number for access to the message text.
•message-number
Either an integer workspace field or an integer literal specifying the integer value assigned to a message identifier. Use either the message identifier or the message number for access to the message text.
•message-group-uuid
Either a UUID-workspace field or a UUID-string literal that uniquely identifies the message group for a system-defined exception code.
The uuid-value specified as a string literal is within double quotes. The format of uuid-value is eight hexadecimal digits, a hyphen, three groups of four hexadecimal digits with each group separated by a hyphen, and twelve hexadecimal digits.
"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
where X is a hexadecimal digit.
If you do not specify a uuid value, the default value is zero.
•message-group-name
An unqualified external identifier giving the name of a message group associated with message catalog containing the text.
•source-field
An integer workspace field that contains a value to identify the origin of the message:
0 System-provided message
1 Application-defined message
•length-field
An integer workspace field that contains the length in characters of the returned text, if LENGTH is specified.
•human-language
A literal or S-text workspace field naming the human language for the message text that ACMSxp software returns in the field specified in INTO. The value of the human language must match a message language name specified in a message group definition. This determines which message group definition to use if multiple message group definitions are associated with the task for the same message group name and UUID.
If you do not specify LANGUAGE in the GET MESSAGE statement, the human language that ACMSxp system uses is determined by how the task is called:
oIf the caller is on another TPsystem, the human language is specified in the task call context.
oIf the caller is on the same TPsystem, the human language set in the environment information of the process running the calling task or in the client program (LOCPATH).
•workspace-field
Text workspace field or fields specifying the areas into which variable text for message parameters in application-defined messages is to be returned. The fields must be defined using the same character set as that of the message-text-field.
The digit in each message parameter determines the order in which the ACMSxp system writes the workspace fields. If there are more message parameters than there are text workspace fields, the results are undefined. If there are excess text workspace fields, the excess are ignored.
If USING is specified for a system-defined message, the ACMSxp software skips it.
•message-text-field
A text workspace field that is to contain the message text received from the ACMSxp system. Define the message text field using a character set that can contain the characters for all human languages that can be encountered during task execution.
A system that supports Japanese and English can use the Kanji character set.
DESCRIPTION
If the GET MESSAGE statement refers to any transactional workspace fields in a noncomposable task, it must be enclosed by a transaction block. The LANGUAGE IS, LENGTH IS, and SOURCE IS clauses can appear in any order.
IN specifies the exception group for a system-defined exception code or the message group for an application-defined exception code. If you omit IN, the exception code must belong to a message group with a UUID of all zeroes. If you specify SOURCE IS APPLICATION or if you specify a source field and the value is 1 (for application), you can specify the message group name.
SOURCE refers to where the message is defined:
oAPPLICATION
For an application-defined message, use either the message identifier or the message number. The value of the message identifier or message number must match a message number defined within a message group definition associated with this task definition. If a match is found, the message text associated with the message number in the message group definition is placed into the message text field.
ACMSxp software retrieves the application message text from the appropriate application message catalog. The environment name ACMS_APPL_MSGCAT_DIR specifies the parent directory for the subdirectories in which the application message catalog files are stored for different languages. Set a value for the name ACMS_APPL_MSGCAT_DIR in the environment variable attribute of the task server entity. See ACMSxp Developing and Managing Applications for information about creating and configuring task server entities.
A different subdirectory is used for each language that the application supports. The subdirectory in which ACMSxp software searches for the message catalog file depends on the language and locale set for the client.
oSYSTEM
For an ACMSxp-defined message, use only the message number. The value of the message number must match an ACMSxp-defined message number. If a match is found, the message text defined by the system is placed into the message text field.
The default source for a message is APPLICATION.
Use the source field when you want to be able to change the SOURCE between APPLICATION and SYSTEM. For example, you can change the SOURCE by using a conditional ASSIGNMENT or by changing the workspace field.
LANGUAGE specifies the human language of the message text field. The value of the human language must match a human language specified in a message group definition. If the called task specifies a language in GET MESSAGE that is other than the language used in the calling task, users can get messages in different languages, depending on the source of the error.
If the human language is ENGLISH, the workspace field specified in INTO can be defined using of any of the character sets. The message text must contain characters from the Simple Latin or ISO Latin 1 execution character sets. If the message text field is defined to be Simple Latin or ISO Latin 1, then no conversion is done.
If the human language is ENGLISH, and the workspace field specified in INTO is defined to be Katakana or Kanji, the characters in the message text are mapped to the equivalent characters in the Katakana or Kanji execution character set.
If the human language is JAPANESE, the workspace field specified in INTO must be defined using the Kanji execution character set. The message text must contain characters from the Kanji execution character set.
If human language is not ENGLISH or JAPANESE, the workspace field specified in INTO must be defined using the required execution character set for that language name. Appendix A contains a table of language names and associated execution character sets.
The GET MESSAGE statement:
1.Retrieves the message text and the text from the workspace fields for any message parameters and substitutes the variable text in the message text.
The digit in the message parameter corresponds to the order of the fields that apply in USING.
2.Stores message text with variable text substituted for message parameters in the field specified in INTO.
3.If LENGTH IS is specified, places the length of the full message into the specified field.
4.Goes to the next statement.
If an exception occurs, the GET MESSAGE statement completes with the exception associated with that condition and the value of the message text field is no longer valid. If LENGTH IS is used, the value of the field is also no longer valid.
EXCEPTIONS
The GET MESSAGE statement can generate the exception classes described in the following sections. The sections describe the conditions leading to the exception class and suggest actions to take.
AP-EXECUTION-FAULT
The AP-EXECUTION-FAULT exception class indicates one of the following error conditions:
oThe subscript used to refer to an element in a fixed-length array is invalid (referring to A(n) where n is less than or equal to one or n is greater than the maximum size of array).
oThe subscript used to refer to an element in a variable-length array is invalid (referring to A(n) where n is less than one or n is greater than the value of the DEPENDING ON field).
oThe value of the DEPENDING ON field used when referring to an element of a variable-length array is invalid (the value of the DEPENDING ON field is less than the minimum size of the array or the value of the DEPENDING ON field is greater than the maximum size of array).
oSource-field specified in SOURCE contains a value other than 0 or 1.
oThe value of the DEPENDING ON field was invalid when referring to a workspace name or workspace field containing a variable-length array.
oThe execution character set used to define the workspace fields specified in INTO or USING cannot handle the human language of the message text being returned.
oIN message-group-name is specified and the value of SOURCE source-field is 0 (for system).
NO-OUTPUT-ERROR
The NO-OUTPUT-ERROR exception class indicates one of the following error conditions:
oThe value of the message number specified in GET MESSAGE did not match a message number defined in the message group definition. No message text is returned.
oThe value of the human language name specified in LANGUAGE IS does not match a human language defined in any message group definition in the message group.
oThe value of the message group UUID specified in IN did not match a known exception group or the value of the message group name specified in IN did not match a known message group definition.
RELATED INFORMATION
Syntax: exception(1), exception_handler(1), message_group(1), statement(1), task_definition(1)