Change Name (CN)

Change Name

This command changes the name of the table or Alternate Index in memory—the status of the newly named table or Alternate Index is open for write.

MOVE 'CN'                   TO xxxx-COMMAND.
CALL 'TBLBASE' USING        TB-PARM
                            xxxx-COMMAND-AREA
                            NEW-TABLE-NAME.

memcpy( tbCommArea.tbCommand, "CN", 2 );
TBLBASE( &tbParm, &tbCommArea, pNewTableName );

NEW-TABLE-NAME—the new name for the table or Alternate Index

The CN command operates on a Data Table or Alternate Index. As a name change could have repercussions to applications that share the table, caution is advised in its use.

The CN command has different effects depending on whether the table is open when the command is issued, and in the case of an Alternate Index, whether it is Invoked (see Invoke Alternate Index (IA)). These cases are outlined below.

CN can also be used to create new tables from a template-table.

In a multi-user environment, if you want to control the user(s) or transactions that perform updates after the CN command (which causes the newly named table to be open for write), place a password in the LOCK-LATCH field when using the CN command. Only the update commands that have the same password in the LOCK-LATCH field are authorized to perform the update. See 9. LOCK-LATCH (8 bytes).

If the Data Table is not open and it has a Read password protecting the table in the library, an attempt to use the CN command on the Data Table or an Alternate Index will return error 0030.

The CN command does not affect the table name in the library.

The new table name indicated by the CN command must be a valid table name (see Table names).

The source table indicated by the CN command must be open or be available in a library in the tableBASE Library List (LIB-LIST).

If an RL command was applied to a newly created table using the Change Name command (CN), in previous releases, this would result in a return code of 38. Starting with Version 6, this returns a zero. A subsequent attempt to change the in-memory table back to open for write (OW) will only work in single user batch where exclusive access is assured. See Release Table (RL).

The table name may not be changed to a name of a table that is already open.

If you want to use the CN command on a table in a VTS-TSR then the VTS name must be in the TB-SUBSYSTEM field of the TB-PARM (see TB-PARM V5 (64 bytes)).

If the Data Table is already open, the Data Table name is changed, and if the table was opened for read its status is changed to open for write. The renamed table is then treated as a new table.

In addition, any Alternate Indexes on this Data Table that are open when the CN is processed will have their status changed to open for write and their Data Table will be changed to the renamed table name. Closed Alternate Indexes are unaffected.

If the CN command is processed and the Data Table is not already open, the Data Table is opened and the table is renamed. The renamed table is then treated as a new table and is open for write.

Read passwords on the Data Table will cause the CN command to fail. Write passwords have no affect.

If the Alternate Index is already opened by an IA command, then the name of the Alternate Index is changed.

If the Alternate Index is already open but not by an IA command, the CN command creates a new table with the new name. This new table uses a copy of the table data from the Data Table that is open in memory with an Index as defined by the Alternate Index. The status of this table is changed to open for write. This table is no longer an Alternate Index but a Data Table.

If the CN command is issued on an Alternate Index which is not already open, the Alternate Index is opened for write. The CN command causes the creation of a new table with the new name. This table uses a copy of the table data from the Data Table that is already open in memory with an Index as defined by the Alternate Index. This table is then treated as a new table. This table is no longer an Alternate Index but a Data Table, and its status is open for write.