Creates an alias for a database. Once an alias
is created, it can be used in place of the database's logical name.
Note: A database can have more than one alias, but each
alias refers to one and only one database.
Syntax
CREATE ALIAS alias-string | value ( expression )
FOR DATABASE logical-name-string | value ( expression )
[ NO-ERROR ]
|
-
alias-string
| value ( expression )
- An unquoted string, quoted string, or CHARACTER expression that
represents an alias for the database.
- FOR DATABASE logical-name-string
| value ( expression )
- An unquoted string, quoted string, or CHARACTER expression that
represents the logical name of the database.
Note: The
logical name must already be set.
- NO-ERROR
- Tells the AVM to allow the alias to be created even if the database
is not connected.
If you CREATE ALIAS for a database that is
not connected and omit NO-ERROR, the AVM reports a run-time error.
Note: The NO-ERROR option of the CREATE ALIAS statement
behaves differently from the NO-ERROR option of other ABL elements.
Example
This
procedure creates the alias myalias for database mydb:
r-cralas.p
CREATE ALIAS myalias FOR DATABASE mydb NO-ERROR
|
Notes
- The
first OpenEdge database connected during a given session receives
the DICTDB alias.
- The first database connected that has an _menu file
automatically receives the alias FTDB. You can reassign the FTDB alias
to any other FAST TRACK database.
- If there is already a database connected with logical name equal
to alias, CREATE ALIAS fails.
- If there is an existing alias equal to alias,
the existing alias is replaced by the new alias.
- If you want to use an expression for an alias name or logical
name, you must use CREATE ALIAS VALUE (expression) FOR
DATABASE VALUE (expression).
- When a given database is disconnected, the existing aliases
that refer to it are not erased, but remain in the session alias
table. Later in the same session, if you connect to a database with
the same logical name, the same alias is used again.
- Aliases allow a general purpose application (such as the OpenEdge Data
Dictionary) to expect a specific database name. The Dictionary only works
on databases with logical name or alias "DICTDB". The end user or the
application can use CREATE ALIAS to provide the correct alias, in case
it is inconvenient to connect the database using the correct logical name.
Also, if there are several connected databases, the application
can ask the user which one to select, then set the alias accordingly.
The Data Dictionary does this when you choose Select Working Database.
- Suppose you connect to a database with logical name MYNAME and compile
a procedure that accesses that database. Normally, the saved r-code
file contains references to MYNAME.
In a later session, when you
want to use the precompiled program, you can connect to your database
with the same logical name (MYNAME), or you can connect with a different
logical name and set up an alias with the statement CREATE ALIAS
"MYNAME" FOR DATABASE logical-name.
- Usually, any alias that exists during the session when you compile
a procedure has no effect on the resulting r-code file. When a procedure
is compiled, the logical name of the database that is accessed within
the procedure is put into the r-code file, not an existing alias.
If a procedure accesses more than one database, all of the logical
names of accessed databases are placed into the r-code file.
However,
any file reference that is qualified with an alias (as opposed to
a logical name) generates a new instance of the file for the compilation. This
new instance causes the r-code to have the alias reference and not
the logical database name reference. Subsequent unqualified references
to that same file within the same block, or nested blocks, will
resolve to the new alias instance following the usual rules for
qualifying. Unqualified references to different files in the same
database do not get the alias name, but get the logical name. Anonymous
references to a file, previously referenced using the alias qualifier,
in a different, non-nested block get the logical name instead of
the alias name.
It is simpler to just connect to a database
with the desired logical name, leave all references unqualified,
not create an alias, and then compile the application. However,
sometimes you cannot precompile. In those cases, if you want to
compile a procedure so that only the alias gets into the r-code
file, then explicitly qualify all file references using the alias. You
might want only the alias to get into the r-code file, so you can compile
and distribute procedures that will run against any database whose
logical name has been assigned the alias contained in the r-code file.
- Changes made to an alias do not take effect within the current
procedure. In the following example, alias1.p fails
to compile when it reaches the FOR EACH statement, because alias myalias has
been created during the compilation:
/* alias1.p */
/* NOTE: this code does NOT work */
CREATE ALIAS myalias FOR DATABASE sports2000.
FOR EACH myalias.Customer NO-LOCK:
DISPLAY Customer.Name.
END.
|
To solve this problem, split r-alias1.p into
two procedures. For example:
r-dispnm.p
FOR EACH myalias.Customer NO-LOCK:
DISPLAY Customer.Name.
END.
|
r-alias2.p
CREATE ALIAS myalias FOR DATABASE sports2000.
RUN r-dispnm.p.
|
CREATE ALIAS affects only subsequent compilations;
currently executing procedures are not affected.
- Be careful when using shared buffers with aliases. If you reference
a shared buffer after changing the alias that initially was used
in defining it, the AVM returns a run-time error. See the following
example procedures for details.
Once procedure r-main.p is
run, it calls r-makebf.p, which calls r-disp6.p. The
alias myalias is created in r-main.p, with
reference to database sports2000. In r-makebf.p,
the shared buffer mybuf is defined for myalias.customer. Then, in
the next line, myalias is changed, so that it now refers to database
sports2. When an attempt is made to reference shared buffer mybuf
in procedure r-disp6.p, a run-time error occurs,
with the message: "r-disp6.p Unable to find shared buffer for mybuf."
r-main.p
CREATE ALIAS myalias FOR DATABASE sports2000.
RUN r-makebf.p.
|
r-makebf.p
DEFINE NEW SHARED BUFFER mybuf FOR myalias.Customer.
CREATE ALIAS myalias FOR DATABASE sports2.
RUN r-disp6.p
|
r-disp6.p
DEFINE SHARED BUFFER mybuf FOR myalias.Customer.
FOR EACH mybuf NO-LOCK:
DISPLAY mybuf.
END.
|
- Be careful when accessing a database sequence with an alias
that points to a different database than the one used when the alias
was defined. If you supply an alias name to the CURRENT-VALUE function or
the NEXT-VALUE function, only the database used to define the alias is
referenced. In this case, it is preferable to use the DYNAMIC-CURRENT-VALUE
function and DYNAMIC-NEXT-VALUE function instead of the CURRENT-VALUE function
and NEXT-VALUE function, respectively.
See also
ALIAS function, CONNECT statement, CONNECTED function, CREATE CALL statement, DATASERVERS function, DBCODEPAGE function, DBCOLLATION function, DBRESTRICTIONS function, DBTYPE function, DBVERSION function, DELETE ALIAS statement, DISCONNECT statement, DYNAMIC-CURRENT-VALUE function, DYNAMIC-NEXT-VALUE function, ERROR-STATUS system handle, FRAME-DB function, LDBNAME function, NUM-DBS function, PDBNAME function, SDBNAME function