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
their own 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 functionBecause 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 their 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

---