10.7.5 Pragma Directives for RepositoryId

   Three pragma directives (id, prefix, and version), are specified to accommodate arbitrary RepositoryId formats and still support the OMG IDL RepositoryId format with minimal annotation. The prefix and version pragma directives apply only to the IDL format. An IDL compiler must interpret these annotations as specified. Conforming IDL compilers may support additional non-standard pragmas, but must not refuse to compile IDL source containing non-standard pragmas that are not understood by the compiler.

   10.7.5.1 The ID Pragma

   An OMG IDL pragma of the format

   #pragma ID <name> “<id>?

   associates an arbitrary RepositoryId string with a specific OMG IDL name. The <name> can be a fully or partially scoped name or a simple identifier, interpreted according to the usual OMG IDL name lookup rules relative to the scope within which the pragma is contained.The <id> must be a repository ID of the form described in Section 10.7, “RepositoryIds,? on page 10-64.

   An attempt to assign a repository ID to the same IDL construct a second time shall be an error unless the repository ID used in the attempt is identical to the previous one.

   interface A {};

   It is also an error to apply an ID to a forward-declared IDL construct (interface, valuetype, structure, and union) and then later assign a different ID to that IDL construct.

   10.7.5.2 The Prefix Pragma

   An OMG IDL pragma of the format:

   #pragma prefix “<string>?

   sets the current prefix used in generating OMG IDL format RepositoryIds. For example, the RepositoryId for the initial version of interface Printer defined on module Office by an organization known as “SoftCo? might be “IDL:SoftCo/Office/Printer:1.0?.

   This format makes it convenient to generate and manage a set of IDs for a collection of OMG IDL definitions. The person creating the definitions sets a prefix (“SoftCo?), and the IDL compiler or other tool can synthesize all the needed IDs.

   Because RepositoryIds may be used in many different computing environments and ORBs, as well as over a long period of time, care must be taken in choosing them. Prefixes that are distinct, such as trademarked names, domain names, UUIDs, and so forth, are preferable to generic names such as “document.?

   The specified prefix applies to RepositoryIds generated after the pragma until the end of the current scope is reached or another prefix pragma is encountered. An IDL file forms a scope for this purpose, so a prefix resets to the previous prefix at the end of the scope of an included file:

   // A.idl #pragma prefix “A?interface A {};

   // B.idl #pragma prefix “B?#include “A.idl?interface B {};

   The repository IDs for interfaces A and B in this case are:

   IDL:A/A:1.0IDL:B/B:1.0

   Similarly, a prefix in an including file does not affect the prefix of an included file:

   // C.idl interface C {};

   // D.idl #pragma prefix “D?#include “C.idl?interface D {};

   The repository IDs for interface C and D in this case are:

   IDL:C:1.0 IDL:D/D:1.0

   If an included file does not contain a #pragma prefix, the current prefix implicitly resets to the empty prefix:

   // E.idl interface E {};

   // F.idl module M {#include <E.idl>

    };

   The repository IDs for module M and interface E in this case are:

   IDL:M:1.0IDL:E:1.0

   If a #include directive appears at non-global scope and the included file contains a prefix pragma, the included file's prefix takes precedence, for example:

   // A.idl #pragma prefix “A?interface A {};

   // B.idl #pragma prefix “B?module M {#include “A.idl?};

   The repository ID for module M and interface A in this case are:

   IDL:B/M:1.0 IDL:A/A:1.0

   Forward-declared constructs (interfaces, value types, structures, and unions) must have the same prefix in effect wherever they appear. Attempts to assign conflicting prefixes to a forward-declared construct result in a compile-time diagnostic. For example:

   #pragma prefix “A?interface A; // Forward decl.

   #pragma prefix “B?interface A; // Compile-time error

   #pragma prefix “C?interface A { // Compile-time errorvoid op();};

   A prefix pragma of the form

   #pragma prefix “?

   resets the prefix to the empty string. For example:

   #pragma prefix “X?interface X {};#pragma prefix “?interface Y {};

   The repository IDs for interface X and Y in this case are:

   IDL:X/X:1.0IDL:Y:1.0

   If a specification contains both a prefix pragma and an ID or version pragma, the prefix pragma does not affect the repository ID for an ID pragma, but does affect the repository ID for a version pragma:

   #pragma prefix “A?interface A {};interface B {};interface C {};#pragma ID B “IDL:myB:1.0?#pragma version C 9.9

   The repository IDs for this specification are

   IDL:A/A:1.0IDL:myB:1.0IDL:A/C:9.9

   A #pragma prefix must appear before the beginning of an IDL definition. Placing a #pragma prefix elsewhere has undefined behavior, for example:

   interface Bar #pragma prefix “foo? // Undefined behavior { // ...

   };

   10.7.5.3 The Version Pragma

   An OMG IDL pragma of the format:

   #pragma version <name> <major>.<minor>

   provides the version specification used in generating an OMG IDL format RepositoryId for a specific OMG IDL name. The <name> can be a fully or partially scoped name or a simple identifier, interpreted according to the usual OMG IDL name lookup rules relative to the scope within which the pragma is contained. The <major> and <minor> components are decimal unsigned shorts.

   If no version pragma is supplied for a definition, version 1.0 is assumed.

   If an attempt is made to change the version of a repository ID that was specified with an ID pragma, a compliant compiler shall emit a diagnostic:

   interface A {};#pragma ID A “IDL:myA:1.1?#pragma version A 9.9 // Compile-time error

   An attempt to assign a version to the same IDL construct a second time shall be an error unless the version used in the attempt is identical to the existing one.

   interface A {};#pragma version A 1.1#pragma version A 1.1 // OK#pragma version A 1.2 // Error

   interface B {};#pragma ID B “IDL:myB:1.2?#pragma version B 1.2 // OK

   10.7.5.4 Generation of OMG IDL - Format IDs

   A definition is globally identified by an OMG IDL - format RepositoryId if no ID pragma is encountered for it.

   The ID string shall be generated by starting with the string "IDL:". Then, if the current prefix pragma is a non-empty string, it is appended, followed by a "/" character. Next, the components of the scoped name of the definition, relative to the scope in which any prefix that applies was encountered, are appended, separated by “/? characters. Finally, a “:? and the version specification are appended.

   For example, the following OMG IDL:

   module M1 { typedef long T1; typedef long T2; #pragma ID T2 “DCE:d62207a2-011e-11ce-88b4-0800090b5d3e:3?

   };

   #pragma prefix “P1?

   module M2 {

   module M3 {#pragma prefix “P2?typedef long T3;

   };typedef long T4;#pragma version T4 2.4

   };

   specifies types with the following scoped names and RepositoryIds:

   ::M1::T1IDL:M1/T1:1.0

   ::M1::T2 DCE:d62207a2-011e-11ce-88b4-0800090b5d3e:3

   ::M2::M3::T3IDL:P2/T3:1.0

   ::M2::T4IDL:P1/M2/T4:2.4

   For this scheme to provide reliable global identity, the prefixes used must be unique. Two non-colliding options are suggested: Internet domain names and DCE UUIDs.

   Furthermore, in a distributed world where different entities independently evolve types, a convention must be followed to avoid the same RepositoryId being used for two different types. Only the entity that created the prefix has authority to create new IDs by simply incrementing the version number. Other entities must use a new prefix, even if they are only making a minor change to an existing type.

   Prefix pragmas can be used to preserve the existing IDs when a module or other container is renamed or moved.

   module M4 {

   #pragma prefix “P1/M2?module M3 {

   #pragma prefix “P2?

   typedef long T3;};typedef long T4;

   #pragma version T4 2.4};

   This OMG IDL declares types with the same global identities as those declared in module M2 above.

   See Section 10.7.5.2, “The Prefix Pragma,? on page 10-68 for further details of the effects of various prefix pragma settings on the generated RepositoryIds.