Using MAKETABLE_SUB (Functions/Subroutines/Programs) [Revelation On-Line Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Using MAKETABLE_SUB (Functions/Subroutines/Programs) ======

======   ======

==== Created at 14 NOV 1996 02:38PM ====




**MAKETABLE_SUB**

**MAKETABLE_SUB( volumeName, tableName, volumeInfo,  **

** columnList, attachFlag)**

** Using MAKETABLE_SUB**

Creates a new Advanced Revelation table, and optionally creates the column definitions for it as well. You can create the table on a specific volume. By default, the new table is not attached (see the //attachFlag// //// parameter, below).

** volumeName**

The name of the volume on which to create the new table. **MAKETABLE_SUB **will initialize a new volume, but will not create it. If you provide no volume name, the new table is created on the default data volume for the current application or user.

To create a table using an Environmental Bond, define a volume using **SETVOLUME**, and then use the volume definition name for the //volumeName// //// parameter.

** tableName**

The name of the table to create. The name must follow standard Advanced Revelation table-name conventions. For details about valid table names, see "About tables" in Chapter 21 of the //Advanced Revelation User's Guide//. (If you are creating a table using an Environmental Bond, the bond determines the rules for valid table names.)

To create both the data and dictionary portion of the table, call **MAKETABLE_SUB **twice, once for the dictionary, and a second time to create the data portion. To create the dictionary portion of a table, use the prefix "**DICT**." on the table name.

If you are creating tables using an Environmental Bond, you should create the dictionary portion of the table before creating the data portion. Be sure to attach the dictionary portion before attempting to create the data portion (see //attachFlag//, below).

By default the table belongs to the current application and has no user name (owner). If you want to create a table that belongs to another application, or qualify the table with a user name, use one of these formats:

userName.tableName

tableName*applicationName

userName.tableName*applicationName

where //userName// //// is the name of the owner, and //applicationName// //// is the name of a different application. The user and application do not already have to exist. To create the dictionary portion of a qualified name, add the prefix "**DICT**." to the full table name (**DICT**.//userName//.//tableName//). For details about user names, see "Table names and users (qualified table names)" in Chapter 22 of the Advanced Revelation //User's Guide//.

** volumeInfo**

An array of information that should be added into the volume directory (media map) entry for the table being created. Under most circumstances, you can pass a null for this parameter. For Advanced Revelation (Linear Hash) tables, the only practical use of this parameter is to add **MFS**s to the table. Use this format:

volumeInfo<2> = MFS1 : @VM : MFS2 : (etc.)

The //volumeInfo// //// array can also include information used when working with Environmental Bonds. For details about the type of information that can be included in volume directory entries, see **MEDIA.MAP.EQUATES **in the **SYSINCLUDE **table.

** columnList**

Use this parameter when creating the dictionary portion of the table to pass an array (@FM-delimited) of columns to create. Each column to be created is one field in //columnList//; provide details about each column as an **@VM**-delimited array with this layout:

|**Value**|**Meaning**                                        |
|<n,1>    |The name of the column.                            |
|<n,2>    |The Advanced Revelation generic data type.         |
|<n,3>    |True if this is a key, otherwise false.            |
|<n,4>    |True if the column is multivalued, otherwise false.|

**MAKETABLE_SUB** fills in the rest of the column definition according to these rules:

  The field name is also used to create the column heading.

  The column length, output conversion, and validation are based on the generic data type.

  Key part number are assigned in order, starting with part zero.

  Column position numbers are assigned in order starting with position 1.

You cannot create symbolic or group dictionary columns (types "**S**" or "**G**") using **MAKETABLE_SUB**.

** attachFlag**

Pass true in this parameter if you want the table to be attached after it has been created. If the flag is false (null), the table is created but not attached. If you created a table that belongs to another application, it cannot be attached using this flag.

** Values returned**

The return status of **MAKETABLE_SUB** is indicated by the system variable //@file.error//. Multiple errors are delimited with record marks (**@RM**). The error number appears in field 1 of each //@file.error// "record", and additional information about the error appears in field 2. Possible errors are:

|**Error**|**Meaning**                                                 |**Add'l**** Info.**                               |
|S140     |This process is not allowed on a Runtime version            |                                                  |
|S141     |No value was provided for the table name.                   |<2,1> subroutine name\\ \\ <2,2> 2 (parameter no.)|
|146      |The table already exists.                                   |<2> table name                                    |
|109      |Invalid volume name.                                        |<2> volume name                                   |
|301      |Invalid data type in //columnList//.                        |<2> column name                                   |
|W506     |Unable to create the table.                                 |<2,1> table name\\ \\ <2,2> volume name           |
|143      |The dictionary has not been created yet (for bonded tables).|                                                  |
|51, 55   |Invalid column information (for bonded tables).             |<2> column name\\ \\                              |

If you are creating a table using an Environmental Bond, the bond may return additional errors. See **SYSMESSAGES** for text corresponding to errors returned by **MAKETABLE_SUB**. If the error returned in field one of //@file.error// is numeric (for example, "143"), add the prefix "**FS**" to the error before looking it up. For example, error 143 becomes **FS**143.

 

Under some circumstances, **MAKETABLE_SUB **sets these values for //status(// //)//:

|**status( )**|**Meaning**                             |
|0            |The table has been created successfully.|
|1            |An error occurred.\\ \\ ** **           |

**Notes**

If there is any error during the creation of the dictionary, then no portion of the file is created. Examples of problems that cause the creation of the dictionary to fail include passing a bad data type in //columnList////.//

** Correct use of MAKETABLE_SUB**

equ true$ to 1

equ false$ to 0

equ null$ to ""

/* for PROGRESS calls */

equ init$ to 0

equ update$ to 2

equ cleanup$ to 3

 

call progress( init$, "", image )

 

volume = 'CUSTDATA'

table = 'INVOICES'

dict = "DICT." : table

fields = "INV_NO,INTEGER,1,0" ; * commas are converted to @VM 

fields<2> = "CUST_NO,CHAR(10),0,0" ; * later in the program

fields<3> = "INV_DATE,DATE,0,1"

fields<4> = "QTY,INTEGER,0,1"

fields<5> = "CODE,VARCHAR,0,1"

fields<6> = "COST,DOLLARS,0,1"

volinfo = ""

attachFlag = true$ ; * attach the table when done

 

convert "," to @vm in fields

 

/* create the dictionary portion first */

call progress( update$, "", "Creating " : dict : " ..." )

call maketable_sub( volume, dict, volinfo, fields, flag )

 

/* now create the data portion */

if @file.error<1> = null$ then

 /* dictionary creation was successful */

 call progress( update$, "", "Creating " : table : " ..." )

 call maketable_sub( volume, table, volinfo, fields, flag )

end

 

/* display any errors */

if @file.error<1> ne null$ then

 call fsmsg()

end else

 call msg("Done creating %1%!", "", "", table[1, "*"] )

end

call progress( cleanup$, "", image )

stop