GenerateGUID function

Description

Creates a globally unique identifier (GUID) that can be used
as a class ID (CLSID) when you register an object and its type library
in the Windows registry. Both the object and its type library have
a GUID.

Controls

PowerBuilder.Application (automation server)

Syntax

Argument	Description
automationobject	When PowerBuilder is the OLE client, the name of the OLEObject instantiated with the PowerBuilder.Application automation server. For other clients, use syntax appropriate for calling a function belonging to an automation object.
REF guidvariable	A string variable, passed by reference, that will hold the string representation of the GUID generated by the function. Because GenerateGUID is called as an automation function whose prototype is not checked by the compiler, you must specify REF to pass guidvariable by reference.

Return Values

Long. Returns a status code indicating
whether an error occurred. Values are:

• 0 A GUID was generated successfully.
• -1 Unable to load the DLL for calling GenerateGUID.
• -2 No network card was found, so a GUID could not be generated.
• -3 Creating a GUID failed.
• -9 Unknown error.

Usage

GenerateGUID requires:

• RPCRT4.DLL,
  in which it calls the function UuidCreate. The DLL must
  be present on your path.
• A network card. The function uses the identification
  information for your network card to generate a unique value.

If you do not meet these conditions, you can contact Microsoft
to obtain GUIDs.

A GUID is a long hexadecimal number that can be represented
as a string in the format (8-4-4-4-12 digits):

The GUID is used in the Windows registry to identify each
program entity. Both the object being registered and its type library
have a GUID.

You cannot perform automation against a PowerBuilder object
until the program object is defined in the registry. GenerateGUID is
a tool to help you create the necessary registry information. When
you generate a GUID, you pass the GUID to the functions GenerateRegFile and GenerateTypeLib to
create registry update files. You use those update files on each
user’s machine to install your object in its registry.

Each time you create a new GUID for your object and update
the registry, a new registry entry is created. If you use the same
GUID in your registry update file, the old registry entry is replaced
with the new one.

When you deploy an update to your object, you can generate
new update files with the same GUID. Existing applications can successfully
access the newly updated object as long as its interface (its properties
and function signatures) remains compatible. However, if you changed
the interface for your object, you should use a new GUID for the
update. Existing applications can continue to use the old object
and new applications can use the new one, taking advantage of changed
and new functionality.

For how to use a PowerBuilder wizard to register
objects, see “Registering the object”.

Examples

This example establishes a PowerBuilder.Application
server session and generates a GUID:

See Also

• GenerateRegFile
• GenerateTypeLib

---