ddlSaveColl() - save a collection to a file

ddlSaveColl() - save a collection to a file

ddlSaveColl() is used to save a collection to a file.

Prototype:

   void ddlSaveColl(
      CONTROL *ctl,
      char *OptnStr,
      char *ArgList);          /* command argument list */

Permitted values in OptnStr: NA

Form of ArgList:

	Where:
	<cxname> represents the source collection name; <tablename> represents the source table name; <filepathname> is the full path name of the target file If required (or if desired), <filepathname> can be enclosed in "s or 's; however, the '#' should not be enclosed in "s or 's.

Description:

The ddlSaveColl() function saves the specified collection to a permanent file.

The saved collection can be referenced later by using the #<filepathname> construct as a collection name in the ddlFind() function. For example,
A CUSTOMERS where #custsave.cx

The scope of a saved collection goes beyond the scope of the current instance. That is
1) the saved collection can be referenced from a different instance than the one that created it;
2) the saved collection can be referenced at a later date.

It is the responsibility of the application developer to assure that the saved collection is still meaningful.

There is a special provision that allows a collection to be saved to memory, rather than to a file. If the first character of the target file name is the character '~', the collection is saved to memory. In this case, no path should be specified in <filepathname>.

The saved collection is referenced in the same manner as a collection that is saved to a file; i.e., with the #<filepathname> construct. However in this case, the scope of the saved collection is limited to the current instance.

Values returned in Control Structure:

Control.Ans1	Number of records in saved collection
Control.Ans2	The size of the saved collection file in bytes [minus 512]
Control.Ans3	If the collection is saved to memory, ctl->Ans3 is a handle to the collection than can be used with the DdBoolEval() API function.