|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
[form] COMMON [name] [,X] [,NOSUFFIX] member_def . . . [ENDCOMMON]
Arguments
form
(optional) Defines the record as one of the following forms:
Causes the statement to allocate data space in a shared data area. If INTERNAL is specified (Synergy .NET only), access is limited to the current assembly.
Causes the statement to reference data space that was allocated by a GLOBAL COMMON statement in another routine.
name
(optional) The name of the record to define. If name isn’t specified, the record is unnamed.
,X
(optional) Indicates that you’re defining an overlay for the most recently defined nonoverlay common. If you specify “,X” on an external common record, the overlay indicator is ignored.
NOSUFFIX
(optional) Indicates that the common record name will not contain a trailing dollar sign ($) when declared or referenced. See the Discussion for more information. (OpenVMS only)
member_def
Either the definition of a field within the record or a group declaration. Each field definition has the syntax described in Defining a field. Each group declaration has the syntax described in GROUP-ENDGROUP. You can specify as many member definitions as you want.
The COMMON statement defines a shared data record and its component fields. A COMMON record can be either GLOBAL, which allocates the data space, or EXTERNAL, which references it. Fields in an EXTERNAL COMMON record reference the data in the GLOBAL COMMON record by defining where the field starts by matching the name. The size of the data referenced in an EXTERNAL COMMON field is defined locally by the size specified and does not have to match the GLOBAL COMMON field’s size.
GLOBAL and EXTERNAL are mutually exclusive. If you don’t specify either one, GLOBAL is the default in a main routine and EXTERNAL is the default in a subroutine or function. You can only define a shared data area once, in one global common record within a program. However, you can reference that data area in any number of external common records within a program. Neither external common records nor global common records are valid in a global data section.
In Synergy .NET, an external common field cannot differ in size or data type from the corresponding global common field. External common and global common declarations must match in every respect for a field. If you have a field whose declarations differ, create an overlay in the global common declaration to match the field in the external common declaration.
For each common record name and field name within a common record, the compiler appends a dollar sign ($) to the end of the name. This sign ensures that common names are unique and do not conflict with global names. Specifying the NOSUFFIX modifier inhibits this dollar sign from being appended on OpenVMS. You might use NOSUFFIX if you’re referencing or defining data for other languages in which the dollar sign is not a valid or reasonable character. If you use NOSUFFIX, be careful that your common name is unique and doesn’t conflict with other global names, including external subroutine and function names.
At least one field definition must be present after the COMMON statement. Initial values are ignored in EXTERNAL COMMON statements, except to determine the size of an automatically sized field designated with a size of *.
You cannot specify common variables with the same name unless they have unique paths. For example, a “Symbol already uniquely defined” error is generated if you specify the following:
common
smith ,a10
common
smith ,a10
The size of the shared data area defined by the COMMON statement is the sum of the sizes of the data areas allocated to all of its members. The size is defined by the global declaration.
|
Object handles are not allowed in common records. Also, a common record cannot be declared within a class. |
Examples
subroutine aaa
arg ,a
global common cmn
fld1 ,a3, "abc"
fld2 ,a4, "defg"
fld3 ,a5, "hijkl"
proc
arg = fld1 ;arg = "abc"
arg = fld2 ;arg = "defg"
arg = fld3 ;arg = "hijkl"
arg = cmn ;arg = "abcdefghijkl"
xreturn
endsubroutine
;Subroutine bbb shows that although the order of the fields has changed,
;the data accessed is the same since the fields are the same size.
;
;The cmn record still accesses the same data as defined in subroutine aaa
;even though the order of the fields locally has changed, since the name
;is matched to the GLOBAL COMMON name and the size is still the same.
subroutine bbb
arg ,a
external common cmn
fld3 ,a5
fld1 ,a3
fld2 ,a4
proc
arg = fld1 ;arg = "abc"
arg = fld2 ;arg = "defg"
arg = fld3 ;arg = "hijkl"
arg = cmn ;arg = "abcdefghijkl"
xreturn
endsubroutine
;Subroutine ccc shows that although the order of the fields is the same,
;the data accessed is different, since the fields are different sizes from
;what was specified when the fields were defined.
;
;The beginning of the data accessed is defined by the name of the field.
;The size of the data accessed is defined locally by the size of the
;local field.
;
;The cmn record still accesses the same data as defined in subroutine aaa
;even though the size of the fields locally has changed, since the name is
;matched to the GLOBAL COMMON name and the size is still the same.
subroutine ccc
arg ,a
external common cmn
fld1 ,a6
fld2 ,a2
fld3 ,a4
proc
arg = fld1 ;arg = "abcdef"
arg = fld2 ;arg = "de"
arg = fld3 ;arg = "hijk"
arg = cmn ;arg = "abcdefghijkl"
xreturn
endsubroutine
