Previous Topic: $3270()

Next Topic: $GLOBAL()

$ALIAS()

Use the $ALIAS() function to enable the establishment and use of tables of aliases. An alias is a string that, when it matches a minimum portion of an alias table entry, will have another value substituted for it.

Syntax

The $ALIAS() function has this syntax:

result = $ALIAS({ADD   },table,{alias      })
                {CREATE}       {width      }
                {DELETE}       {name,object}
                {LIST  }       {name       }
                {XLATE }

Arguments

The $ALIAS() function takes these arguments:

result

Contains one of these values:

(any successful list operation): Maximum length of any instance of name, followed by the maximum length of any instance of object (separated by a blank).

(any other successful operation): Affirmative message.

(any unsuccessful operation): Error text.

ADD

Adds an alias entry.

CREATE

Creates a new alias table.

DELETE

Deletes an alias entry.

LIST

Lists the contents of an alias table. Entries are returned on the stack, one entry per record. Fields are blank-delimited and consist of:

  • Alias name, in both uppercase and lowercase characters, representing the minimum required string.
  • Minimum required length.
  • Object string for translation.

XLATE

Translates the given alias string into an object.

table

Name of an alias table. This is an arbitrary name. It should not begin with a dollar sign ($), since these names are reserved for use by CA.

alias

Character string to be used in a search of the alias table. This string is not case-sensitive.

width

Maximum number of characters that can appear in any object in the table being created.

name

Name to be added to the table as an alias. The first character must be an uppercase character. During comparisons, the leading uppercase portion of the name must be present in the alias being checked. The remaining characters in the alias being checked (if any) must then match the trailing, lowercase portion of the name. When specified with a DELETE operation, the case is not checked.

object

Text string that is returned upon match by an alias.

Return Codes

The $ALIAS() function produces these return codes:

101 - 103 ARG n MISSING OR INVALID

121 TABLE ALREADY EXISTS

122 TABLE DOES NOT EXIST

123 NO REQUIRED CHARACTERS

124 THIS ENTRY MATCHES EXISTING ENTRY

125 ALIAS NOT FOUND

Example

$ALIAS('CREATE',TAB1,80)
 $ALIAS('ADD',tab1,'ABCdef','xyz')
 $ALIAS('XLATE',tab1,'abc')     == 'xyz'
$ALIAS('XLATE',tab1,'ab')      == 'ALIAS NOT FOUND'
$ALIAS('XLATE',tab1,'abcdefx') == 'ALIAS NOT FOUND'
$ALIAS('XLATE',tab1,'abcde')   == 'xyz'