Using MAKETABLE_SUB (Functions/Subroutines/Programs)

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 MFSs 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:

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:

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 FS143.

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

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