CREATE ALIAS statement

Creates an alias for a database. Once an alias is created, it can be used in place of the database's logical name.

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