/* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Procedure $NAME$ __dbCopyStruct() $CATEGORY$ API $SUBCATEGORY$ Database $ONELINER$ Create a new database based on current database structure $SYNTAX$ __dbCopyStruct( , [] ) $ARGUMENTS$ is the name of the new database file to create. `.dbf` is the default extension if none is given. is an array where each element is a field name. Names could be specified as uppercase or lowercase. $DESCRIPTION$ __dbCopyStruct() create a new empty database file with a structure that is based on the currently open database in this work-area. If is empty, the newly created file would have the same structure as the currently open database. Else, the new file would contain only fields that exactly match . __dbCopyStruct() can be use to create a sub-set of the currently open database, based on a given field list. `COPY STRUCTURE` command is preprocessed into __dbCopyStruct() function during compile time. $EXAMPLES$ // Create a new file that contain the same structure USE test __dbCopyStruct( "mycopy.dbf" ) // Create a new file that contain part of the original structure LOCAL aList USE test aList := { "NAME" } __dbCopyStruct( "onlyname.dbf", aList ) $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $FILES$ Library is rdd $SEEALSO$ COPY STRUCTURE, COPY STRUCTURE EXTENDED, dbCreate(), dbStruct(), __dbCopyXStruct(), __dbCreate(), __dbStructFilter() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Command $NAME$ COPY STRUCTURE $CATEGORY$ Command $SUBCATEGORY$ Database $ONELINER$ Create a new database based on current database structure $SYNTAX$ COPY STRUCTURE TO [FIELDS ] $ARGUMENTS$ `TO xcFileName` is the name of the new database file to create. `.dbf` is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses. `FIELDS `field,...` is an optional list of field names to copy from the currently open database in the specified order, the default is all fields. Names could be specified as uppercase or lowercase. $DESCRIPTION$ `COPY STRUCTURE` create a new empty database file with a structure that is based on the currently open database in this work-area. `COPY STRUCTURE` can be use to create a sub-set of the currently open database, based on a given field list. `COPY STRUCTURE` command is preprocessed into __dbCopyStruct() function during compile time. $EXAMPLES$ // Create a new file that contains the same structure USE test COPY STRUCTURE TO MyCopy // Create a new file that contains part of the original structure USE test COPY STRUCTURE TO SomePart FIELDS name, address $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $SEEALSO$ COPY STRUCTURE EXTENDED, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate(), __dbStructFilter() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Function $NAME$ __dbCopyXStruct() $CATEGORY$ API $SUBCATEGORY$ Database $ONELINER$ Copy current database structure into a definition file $SYNTAX$ __dbCopyXStruct( ) --> lSuccess $ARGUMENTS$ is the name of target definition file to create. `.dbf` is the default extension if none is given. $RETURNS$ __dbCopyXStruct() returns .F. if no database is *used* in the current work-area, .T. on success, or a run-time error if the file create operation had failed. $DESCRIPTION$ __dbCopyXStruct() create a new database named with a pre-defined structure (also called "structure extended file"): Field name Type Length Decimals FIELD_NAME C 10 0 FIELD_TYPE C 1 0 FIELD_LEN N 3 0 FIELD_DEC N 3 0
Each record in the new file contains information about one field in the original file. `CREATE FROM` could be used to create a database from the structure extended file. For prehistoric compatibility reasons, Character fields which are longer than 255 characters are treated in a special way by writing part of the length in the FIELD_DEC according to the following formula (this is done internally): FIELD->FIELD_DEC := Int( nLength / 256 ) FIELD->FIELD_LEN := nLength % 256 Later if you want to calculate the length of a field you can use the following formula: nLength := iif( FIELD->FIELD_TYPE == "C", ; FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN, ; FIELD->FIELD_LEN ) `COPY STRUCTURE EXTENDED` command is preprocessed into __dbCopyXStruct() function during compile time. $EXAMPLES$ // Open a database, then copy its structure to a new file, // Open the new file and list all its records USE test __dbCopyXStruct( "teststru" ) USE teststru LIST $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $FILES$ Library is rdd $SEEALSO$ COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE, CREATE FROM, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCreate() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Command $NAME$ COPY STRUCTURE EXTENDED $CATEGORY$ Command $SUBCATEGORY$ Database $ONELINER$ Copy current database structure into a definition file $SYNTAX$ COPY STRUCTURE EXTENDED TO $ARGUMENTS$ The name of the target definition file to create. `.dbf` is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses. $DESCRIPTION$ `COPY STRUCTURE EXTENDED` create a new database named with a pre-defined structure (also called "structure extended file"): Field name Type Length Decimals FIELD_NAME C 10 0 FIELD_TYPE C 1 0 FIELD_LEN N 3 0 FIELD_DEC N 3 0
Each record in the new file contains information about one field in the original file. `CREATE FROM` could be used to create a database from the structure extended file. For prehistoric compatibility reasons, Character fields which are longer than 255 characters are treated in a special way by writing part of the length in the FIELD_DEC according to the following formula (this is done internally): FIELD->FIELD_DEC := Int( nLength / 256 ) FIELD->FIELD_LEN := nLength % 256 Later if you want to calculate the length of a field you can use the following formula: nLength := iif( FIELD->FIELD_TYPE == "C", ; FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN, ; FIELD->FIELD_LEN ) `COPY STRUCTURE EXTENDED` command is preprocessed into __dbCopyXStruct() function during compile time. $EXAMPLES$ // Open a database, then copy its structure to a new file, // Open the new file and list all its records USE test COPY STRUCTURE EXTENDED TO teststru USE teststru LIST $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $SEEALSO$ COPY STRUCTURE, CREATE, CREATE FROM, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Function $NAME$ __dbCreate() $CATEGORY$ API $SUBCATEGORY$ Database $ONELINER$ Create structure extended file or use one to create new file $SYNTAX$ __dbCreate( , [], [], [], [] ) --> lUsed $ARGUMENTS$ is the target file name to create and then open. `.dbf` is the default extension if none is given. is an optional structure extended file name from which the target file is going to be built. If omitted, a new empty structure extended file with the name is created and opened in the current work-area. is RDD name to create target with. If omitted, the default RDD is used. is an optional logical expression, (.T.) opens the target file name in the next available unused work-area and makes it the current work-area. (.F.) opens the target file in the current work-area. Default value is (.F.). The value of is ignored if is not specified. is an optional alias to USE the target file with. If not specified, alias is based on the root name of . $RETURNS$ __dbCreate() returns (.T.) if there is database *used* in the current work-area (this might be the newly selected work-area), or (.F.) if there is no database *used*. Note that on success a (.T.) would be returned, but on failure you probably end up with a run-time error and not a (.F.) value. $DESCRIPTION$ __dbCreate() works in two modes depending on the value of : 1) If is empty or not specified a new empty structure extended file with the name is created and then opened in the current work-area ( is ignored). The new file has the following structure: Field name Type Length Decimals FIELD_NAME C 10 0 FIELD_TYPE C 1 0 FIELD_LEN N 3 0 FIELD_DEC N 3 0
The CREATE command is preprocessed into the __dbCopyStruct() function during compile time and uses this mode. 2) If is specified, it is opened and assumed to be a structure extended file where each record contains at least the following fields (in no particular order): FIELD_NAME, FIELD_TYPE, FIELD_LEN and FIELD_DEC. Any other field is ignored. From this information the file is then created and opened in the current or new work-area (according to ), if this is a new work-area it becomes the current. For prehistoric compatibility reasons, structure extended file Character fields which are longer than 255 characters should be treated in a special way by writing part of the length in the FIELD_DEC according to the following formula: FIELD->FIELD_DEC := Int( nLength / 256 ) FIELD->FIELD_LEN := nLength % 256 `CREATE FROM` command is preprocessed into __dbCopyStruct() function during compile time and use this mode. $EXAMPLES$ // CREATE a new structure extended file, append some records and // then CREATE FROM this file a new database file __dbCreate( "template" ) dbAppend() FIELD->FIELD_NAME := "CHANNEL" FIELD->FIELD_TYPE := "N" FIELD->FIELD_LEN := 2 FIELD->FIELD_DEC := 0 dbAppend() FIELD->FIELD_NAME := "PROGRAM" FIELD->FIELD_TYPE := "C" FIELD->FIELD_LEN := 20 FIELD->FIELD_DEC := 0 dbAppend() FIELD->FIELD_NAME := "REVIEW" FIELD->FIELD_TYPE := "C" // this field is 1000 char long FIELD->FIELD_LEN := 232 // 1000 % 256 = 232 FIELD->FIELD_DEC := 3 // 1000 / 256 = 3 dbCloseArea() __dbCreate( "TV_Guide", "template" ) $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $FILES$ Library is rdd $SEEALSO$ COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE, CREATE FROM, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCopyXStruct() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Command $NAME$ CREATE $CATEGORY$ Command $SUBCATEGORY$ Database $ONELINER$ Create empty structure extended file $SYNTAX$ CREATE [VIA ] [ALIAS ] $ARGUMENTS$ is the target file name to create and then open. `.dbf` is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses. `VIA xcRDDName` is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses. `ALIAS xcAlias` is an optional alias to USE the target file with. If not specified, alias is based on the root name of . $DESCRIPTION$ CREATE a new empty structure extended file with the name and then open it in the current work-area. The new file has the following structure: Field name Type Length Decimals FIELD_NAME C 10 0 FIELD_TYPE C 1 0 FIELD_LEN N 3 0 FIELD_DEC N 3 0
CREATE command is preprocessed into __dbCopyStruct() function during compile time and use this mode. $EXAMPLES$ // CREATE a new structure extended file, append some records and // then CREATE FROM this file a new database file CREATE template dbAppend() FIELD->FIELD_NAME := "CHANNEL" FIELD->FIELD_TYPE := "N" FIELD->FIELD_LEN := 2 FIELD->FIELD_DEC := 0 dbAppend() FIELD->FIELD_NAME := "PROGRAM" FIELD->FIELD_TYPE := "C" FIELD->FIELD_LEN := 20 FIELD->FIELD_DEC := 0 dbAppend() FIELD->FIELD_NAME := "REVIEW" FIELD->FIELD_TYPE := "C" // this field is 1000 char long FIELD->FIELD_LEN := 232 // 1000 % 256 = 232 FIELD->FIELD_DEC := 3 // 1000 / 256 = 3 dbCloseArea() CREATE TV_Guide FROM template $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $SEEALSO$ COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE FROM, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Command $NAME$ CREATE FROM $CATEGORY$ Command $SUBCATEGORY$ Database $ONELINER$ Create new database file from a structure extended file $SYNTAX$ CREATE FROM [VIA ] [NEW] [ALIAS ] $ARGUMENTS$ is the target file name to create and then open. `.dbf` is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses. `FROM xcFileFrom` is a structure extended file name from which the target file is going to be built. It can be specified as literal file name or as a character expression enclosed in parentheses. `VIA xcRDDName` is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses. `NEW` open the target file name in the next available unused work-area and making it the current work-area. If omitted open the target file in current work-area. `ALIAS xcAlias` is an optional alias to USE the target file with. If not specified, alias is based on the root name of . $DESCRIPTION$ `CREATE FROM` open a structure extended file where each record contain at least the following fields (in no particular order): FIELD_NAME, FIELD_TYPE, FIELD_LEN and FIELD_DEC. Any other field is ignored. From this information the file is then created and opened in the current or new work-area (according to the NEW clause), if this is a new work-area it becomes the current. For prehistoric compatibility reasons, structure extended file Character fields which are longer than 255 characters should be treated in a special way by writing part of the length in the FIELD_DEC according to the following formula: FIELD->FIELD_DEC := Int( nLength / 256 ) FIELD->FIELD_LEN := nLength % 256 `CREATE FROM` command is preprocessed into __dbCopyStruct() function during compile time and uses this mode. $EXAMPLES$ // See example in the CREATE command $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $SEEALSO$ COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Function $NAME$ __FLedit()* $CATEGORY$ API $SUBCATEGORY$ Database $ONELINER$ Filter a database structure array $SYNTAX$ __FLedit( , [] ) --> aStructFiltered $ARGUMENTS$ is a multidimensional array with database fields structure, which is usually the output from dbStruct(), where each array element has the following structure: Position Description dbstruct.ch 1 cFieldName DBS_NAME 2 cFieldType DBS_TYPE 3 nFieldLength DBS_LEN 4 nDecimals DBS_DEC
is an array where each element is a field name. Names could be specified as uppercase or lowercase. $RETURNS$ __FLedit() return a new multidimensional array where each element is in the same structure as the original , but the array is built according to the list of fields in . If is empty, __FLedit() return reference to the original array. $DESCRIPTION$ __FLedit() can be use to create a sub-set of a database structure, based on a given field list. Note that field names in _must_ be specified in uppercase or else no match would be found. `SET EXACT` has no effect on the return value. __FLedit() is a compatibility function and it is synonym for __dbStructFilter() which does exactly the same. $EXAMPLES$ // FIXME LOCAL aStruct, aList, aRet aStruct := { ; { "CODE", "N", 4, 0 }, ; { "NAME", "C", 10, 0 }, ; { "PHONE", "C", 13, 0 }, ; { "IQ", "N", 3, 0 } } aList := { "IQ", "NAME" } aRet := __FLedit( aStruct, aList ) // { { "IQ", "N", 3, 0 }, { "NAME", "C", 10, 0 } } aRet := __FLedit( aStruct, {} ) ? aRet == aStruct // .T. aList := { "iq", "NOTEXIST" } aRet := __FLedit( aStruct, aList ) // { { "IQ", "N", 3, 0 } } aList := { "NOTEXIST" } aRet := __FLedit( aStruct, aList ) // {} // Create a new file that contain part of the original structure LOCAL aStruct, aList, aRet USE test aStruct := dbStruct() aList := { "NAME" } dbCreate( "onlyname.dbf", __FLedit( aStruct, aList ) ) $STATUS$ R $COMPLIANCE$ CA-Cl*pper has internal undocumented function named __FLedit(), in Harbour we name it __dbStructFilter(). The new name gives a better description of what this function does. In Harbour __FLedit() simply calls __dbStructFilter() and therefor the latter is the recommended function to use. This function is only visible if src/rdd/dbstrux.prg was compiled with the HB_CLP_UNDOC flag. $PLATFORMS$ All $FILES$ Header file is dbstruct.ch Library is rdd $SEEALSO$ dbCreate(), dbStruct(), __dbCopyStruct(), __dbStructFilter() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Chen Kedem $TEMPLATE$ Function $NAME$ __dbStructFilter() $CATEGORY$ API $SUBCATEGORY$ Database $ONELINER$ Filter a database structure array $SYNTAX$ __dbStructFilter( , [] ) --> aStructFiltered $ARGUMENTS$ is a multidimensional array with database fields structure, which is usually the output from dbStruct(), where each array element has the following structure: Position Description dbstruct.ch 1 cFieldName DBS_NAME 2 cFieldType DBS_TYPE 3 nFieldLength DBS_LEN 4 nDecimals DBS_DEC
is an array where each element is a field name. Names could be specified as uppercase or lowercase. $RETURNS$ __dbStructFilter() return a new multidimensional array where each element is in the same structure as the original , but the array is built according to the list of fields in . If is empty, __dbStructFilter() return reference to the original array. $DESCRIPTION$ __dbStructFilter() can be use to create a sub-set of a database structure, based on a given field list. Note that field names in _must_ be specified in uppercase or else no match would be found. `SET EXACT` has no effect on the return value. $EXAMPLES$ // FIXME LOCAL aStruct, aList, aRet aStruct := { ; { "CODE", "N", 4, 0 }, ; { "NAME", "C", 10, 0 }, ; { "PHONE", "C", 13, 0 }, ; { "IQ", "N", 3, 0 } } aList := { "IQ", "NAME" } aRet := __dbStructFilter( aStruct, aList ) // { { "IQ", "N", 3, 0 }, { "NAME", "C", 10, 0 } } aRet := __dbStructFilter( aStruct, {} ) ? aRet == aStruct // .T. aList := { "iq", "NOTEXIST" } aRet := __dbStructFilter( aStruct, aList ) // { { "IQ", "N", 3, 0 } } aList := { "NOTEXIST" } aRet := __dbStructFilter( aStruct, aList ) // --> {} // Create a new file that contain part of the original structure LOCAL aStruct, aList, aRet USE test aStruct := dbStruct() aList := { "NAME" } dbCreate( "onlyname.dbf", __dbStructFilter( aStruct, aList ) ) $STATUS$ R $COMPLIANCE$ __dbStructFilter() is a Harbour extension. CA-Cl*pper has an internal undocumented function named __FLedit() that does exactly the same thing. The new name gives a better description of what this function does. $PLATFORMS$ All $FILES$ Header file is dbstruct.ch Library is rdd $SEEALSO$ dbCreate(), dbStruct(), __dbCopyStruct(), __FLedit()* $END$ */