NAME (set external name)

Top  Previous  Next

 

NAME( [name] )

NAME

Specifies an external name.

name

A string constant containing the external name or the label of a static string variable. This may be declared as Global data, Module data, or Local data with the STATIC attribute.

The NAME attribute (PROP:NAME) specifies an external name. The NAME attribute is completely independent of the EXTERNAL attribute--there is no required connection between the two, although both attributes may be used on the same declaration.

The NAME attribute may be placed on a PROCEDURE Prototype, FILE, KEY, INDEX, MEMO, any field declared within a FILE, any field declared within a QUEUE structure, or any variable not declared within a structure. The NAME attribute has different implications depending on where it is used.

PROCEDURE Prototype Usage

NAME may be specified on a PROCEDURE Prototype. The name supplies the external name used by the linker to identify the procedure or function from an external library.

Variable Usage

NAME may be used on any variable declared outside of any structure. This provides the linker with an external name to identify a variable declared in an external library. If the variable also has the EXTERNAL attribute, it is declared, and its memory is allocated, as a public variable in the external library. Without the EXTERNAL attribute, it is declared, and its memory is allocated, in the Clarion program, and it is declared as an external variable in the external library.

FILE Usage

On a FILE statement, NAME specifies the filename of the data file for the file driver. If the name does not contain a drive and path, the current drive and directory are assumed. If the extension is omitted, the directory entry assumes the file driver's default value.

Some file drivers require that KEYs, INDEXes, or MEMOs be in separate files. Therefore, a NAME may also be placed on a KEY, INDEX, or MEMO declaration. A NAME attribute without a name parameter defaults to the label of the declaration statement on which it is placed (including any specified prefix).

NAME may be used on any field declared within a RECORD structure (the name parameter must be a constant, in this case). This provides the file driver with the name of a field as it may be used in that driver's file system.

You can dynamically change the name of a field within a FILE using PROP:NAME as an array. The array element number references the ordinal position of the field within the FILE.

The NAME attribute is considered a part of the file structure, and care should be taken not to have threaded variables used by NAME referenced by non-threaded files.

 

For example:

FileName STRING(255)

TFileName STRING(255),THREAD

 

File FILE,NAME(TFileName)                  !Wrong

File FILE,NAME(FileName)                   !Valid

File FILE,NAME(TFileName),THREAD           !Valid

File FILE,NAME(FileName),THREAD            !Valid

 

 

QUEUE Usage

The NAME attribute on a variable declared in a QUEUE structure specifies an external name for queue processing. The name provides an alternate method of addressing the variables in the QUEUE which may be used by the SORT, GET, PUT, and ADD statements.

Example:

PROGRAM

MAP

 MODULE('External.Obj')

AddCount PROCEDURE(LONG),LONG,C,NAME('_AddCount')   !C function named '_AddCount'

 END

END

 

Cust  FILE,DRIVER('Topspeed')PRE(Cus),NAME(CustName)!Filename in CustName variable

CustKey  KEY('Name'),NAME('c:\data\cust.idx')       !Declare key, cust.idx

Record   RECORD

Name      STRING(20)                                !Default NAME to 'Cus:Name'

        END

     END

 

SortQue QUEUE

Field1   STRING(10),NAME('FirstField')              !QUEUE SORT NAME

Field2   LONG,NAME('SecondField')                   !QUEUE SORT NAME

       END

 

CurrentCnt LONG,EXTERNAL,NAME('Cur')                !Field declared public in

                                                   ! external library as 'Cur'

TotalCnt  LONG,NAME('Tot')                          !Field declared external

                                                   ! in external library as 'Tot'

CODE

OPEN(Cust)

Cust{PROP:NAME,1} = 'Fred'                         !Cus:Name field now referenced as 'Fred'

 

See Also:

PROCEDURE Prototypes

QUEUE

SORT

GET

PUT

ADD

FILE

KEY

INDEX

EXTERNAL