SYNONYM

Read syntax diagramSkip visual syntax diagram SYNonym fnSYNONYMAftAfm*(STD(1STDNOSTDCLEAR)
Notes:
  • 1 You can enter Options in any order between the parentheses.

Authorization

General User

Purpose

Use the SYNONYM command to invoke a table of synonyms to be used with, or in place of, CMS and user-written command names. You create the table yourself using the editor. To specify entries for the table, see the section after the Usage Notes section called The User Synonym Table.

The names you define can be used either instead of or with the standard CMS command truncations. However, no matter what truncations, synonyms, or truncations of the synonyms are in effect, the full real name of the command is always accepted.

Operands

fn
is the file name of the file containing your synonyms table.
ft
is the file type of the file containing your synonyms table. SYNONYM is the default file type.
fm
is the file mode of the file containing your synonyms; if omitted, your disk or directory accessed as A and its extensions are searched. If you specify fm, you must enter the keyword, SYNONYM. If you specify fm as an asterisk (*), all accessed disks and directories are searched for the specified SYNONYM file.

Options

STD
specifies standard CMS abbreviations are accepted. This is the default.
NOSTD
standard CMS abbreviations are not to be accepted. (The full CMS command and the synonyms you defined can still be used.)
CLEAR
removes any synonym table set by a previously entered SYNONYM command.

Usage Notes

  1. If you enter the SYNONYM command with no operands, the system synonym table and the user synonym table (if one exists) are listed.
  2. The SET ABBREV ON or OFF command, with the SYNONYM command, determines which standard and user-defined forms of a particular CMS command are acceptable.
  3. The SYNONYM command cannot define national language translations.
  4. An exec procedure can be invoked by its synonym if the implied exec (IMPEX) function is on. However, within a CMS EXEC or EXEC2 procedure, only the file name of the exec being invoked can be used. A synonym is not recognized within a CMS EXEC or EXEC2 procedure because the synonym tables are not searched during processing of these procedures. Synonym tables can be checked during REXX exec processing, so synonyms can be used to invoke another exec.
  5. When ABBREV is OFF, the synonyms defined for command names (EXECs and MODULEs) are valid, but abbreviations are ignored.

The User Synonym Table

You create the synonym table using the CMS editor. The table must be a file with the file type SYNONYM. The file consists of 80-byte fixed-length records in free-form format with columns 73-80 ignored. The format for each record is:
systemcommand usersynonym count
Where:
systemcommand
is the name of the CMS command or MODULE or exec file for which you are creating a synonym.
usersynonym
is the synonym you are assigning to the command name. When you create the synonym, you must follow the same syntax rules as for commands; that is, you must use the character set used to create commands, the synonym may be no longer than eight characters, and so on.
count
is the minimum number of characters that must be entered for the synonym to be accepted by CMS. If omitted, the entire synonym must be entered. For more information, see the MYSYN example below.
Note: By default CMS translates commands entered on the command line into uppercase. Therefore, you should enter your synonyms in the table in uppercase.

A table of command synonyms is built from the contents of this file. You may have several synonym files but only one may be active at a time.

For example, if the synonym file named MYSYN contains:
MOVEFILE  MVIT
then, after you have issued the command:
synonym mysyn
the synonym MVIT can be entered as a command name to execute the MOVEFILE command. It cannot be truncated because no count is specified. If MYSYN SYNONYM contains:
ACCESS GETDISK 3
the synonyms GET, GETD, GETDI, GETDIS, or GETDISK can be entered as the command name instead of ACCESS.
If you have an exec file named TDISK, you might have a synonym entry:
TDISK TDISK 2
so you can invoke the exec procedure by specifying the truncation TD.

The Relationship between the SET ABBREV and SYNONYM Commands

The default values of the SET and SYNONYM commands are such that the system synonym abbreviation table is available unless otherwise specified.

The system synonym abbreviation table for the FILEDEF command states FI is the minimum truncation. Therefore, the acceptable abbreviations for FILEDEF are: FI, FIL, FILE, FILED, FILEDE, and FILEDEF. The system synonym abbreviation table is available whenever both SET ABBREV ON and SYNONYM (STD) are in effect.

If you have a synonym table with the file identification USERTAB SYNONYM A, that has the entry:
FILEDEF USENAME 3
USENAME is a synonym for FILEDEF, and acceptable truncations of USENAME are: USE, USEN, USENA, USENAM, and USENAME. The user synonym abbreviation table is available whenever both SET ABBREV ON and SYNONYM USERTAB are specified.

No matter what synonyms and truncations are defined, the full real name of the command is always in effect.

Table 1 shows the forms of the system command and user synonyms available for the various combinations of the SET ABBREV and SYNONYM commands.
Table 1. System and User-Defined Truncations
Options Acceptable Command Forms Comments
SET ABBREV ON
SYNONYM USERTAB (STD
FI
FIL

FILEDEF
USE
USEN

USENAME
The ABBREV ON option of the SET command and the STD option of the SYNONYM command make the system table available. The user synonym, USENAME, is available because the synonym table (USERTAB) is specified on the SYNONYM command. The truncations for USENAME are available because SET ABBREV ON was specified with the USERTAB also available.
SET ABBREV OFF
SYNONYM USERTAB (STD
FILEDEF
USENAME
The user-defined synonym, USENAME, is permitted because the user synonym table (USERTAB) is specified on the SYNONYM command. No system or user truncations are permitted.
SET ABBREV ON
SYNONYM USERTAB (NOSTD
FILEDEF
USE
USEN

USENAME
The system synonym table is unavailable because the NOSTD option is specified on the SYNONYM command. The user synonym, USENAME, is available because the user synonym table (USERTAB) is specified on the SYNONYM command and the truncations of USENAME are permitted because SET ABBREV ON is specified with USERTAB also available.
SET ABBREV OFF
SYNONYM USERTAB (NOSTD
FILEDEF
USENAME
The system synonym table is made unavailable either by the SET ABBREV OFF command or by the SYN (NOSTD command. The synonym, USENAME, is permitted because the user-defined synonym table (USERTAB) is specified on the SYNONYM command. The truncations for USENAME are not permitted because the SET ABBREV OFF option is in effect.
SET ABBREV ON
SYNONYM (CLEAR STD
FI
FIL

FILEDEF
The user-defined table is now unavailable. The system synonym table is available because both the ABBREV ON option of the SET command and the STD option of the SYNONYM command are specified.
SET ABBREV OFF
SYNONYM (CLEAR STD
SET ABBREV ON
SYNONYM (CLEAR NOSTD
SET ABBREV OFF
SYNONYM (CLEAR NOSTD
FILEDEF
Because CLEAR is specified on the SYNONYM command, the synonym and its truncations are no longer available. Either the SET ABBREV OFF command or the SYNONYM (NOSTD command make the system synonym table unavailable.
Note: This table does not apply to execs.

Responses

When you enter the SYNONYM command with no operands, the synonym table(s) currently in effect are displayed.
SYSTEM     USER       SHORTEST
command    synonym    form (if any)
   .          .         .
   .          .         .
   .          .         .
This response is the same as the response to the command QUERY SYNONYM ALL.
DMS711I  No system synonyms in effect

This response is displayed when you issue the SYNONYM command with no operands after the command SYNONYM (NOSTD) has been issued.

DMS712I  No synonyms (DMSINA not in nucleus)

The system routine which handles SYNONYM command processing is not in the system.

Messages and Return Codes

  • DMS002E File [fn [ft [fm ]]] not found [RC=28]
  • DMS003E Invalid option: option [RC=24]
  • DMS007E File fn ft fm [is] not fixed, 80-character records [RC=32]
  • DMS056E File fn ft [fm] contains invalid record formats[RC=32]
  • DMS066E option1 and option2 are conflicting options [RC=24]
  • DMS104S Error nn reading file fn ft fm from disk or directory [RC=31│55│70│76│99│100]
  • DMS257T Internal system error at address addr (offset offset)
  • DMS1144E Implicit rollback occurred for work unit workunitid [RC=31]
  • DMS1229E fn ft fm is empty [RC=88]
  • DMS1252T Rollback unsuccessful for file pool filepoolid

Additional system messages may be issued by this command. The reasons for these messages and their location are:

Reason Location
Errors in command syntax Command Syntax Error Messages
Errors in using a file File Error Messages