%DocDB.Database

If a persistent class uses %Storage.Persistent then the USEEXTENTSET parameter is used to specify the global naming strategy used by the default storage class (%Storage.Persistent). If TRUE, then global names are generated for each index that is not already allocated a LOCATION in the active storage definition.

If the storage definition specifies EXTENTLOCATION then that value is used as the base reference for all globals assigned to indices that do not have an explicit LOCATION assigned.

The global name generator for USEEXTENTSET = TRUE honors the package prefix defined in the Package Definition. If none is defined then the package prefix is generated using a based-62 encoded integer produced from CRC32 of the package name. The specific class identifier is generated from the unqualified class name using the same hash (class->crc32->base62) to form EXTENTLOCATION. Specific index suffixes are produced using a generated offset that is local to the first persistent class with an enumerated extent in which the index appears (either defined or inherited).

There are several factors that influence the generation of EXTENTLOCATION:

1. If the EXTENTLOCATION keyword is defined then its value is used,
2. If the DEFAULTGLOBAL class parameter is defined then its value is used,
3. otherwise, the value is generated as two dot delimited segments. The first segment is either the defined package prefix retrieved from the package definition global or, if none is defined, a hash of the package name. The second segment is generated by a hash of the unqualified class name. The hash used is a base 62 encoded CRC32 of the value. For example, Sample.Person produces ^EW3K.wPC9 if no package prefix is defined.

EXTENTLOCATION is specific to each class. When a persistent class extends another persistent class, forming a subextent, then the subclass's EXTENTLOCATION is specific to that subclass. The index location for any inherited index is already defined specifically in the superclass so the subclass's EXTENTLOCATION will only be used as the base for any index that originates in the subclass. For example, Sample.Employee extends Sample.Person. The EXTENTLOCATION generated for Sample.Person is ^EW3K.wPC9 and the EXTENTLOCATION for Sample.Employee is ^EW3K.D1Ex. Since Sample.Employee inherits several indices from Sample.Person, the global name assigned to each of those indices is already defined and inherited by Sample.Employee. However, any index defined in Sample.Employee and not inherited from Sample.Person will be assigned a global name based on Sample.Employee's EXTENTLOCATION, not on Sample.Person's EXTENTLOCATION. In other words, the EXTENTLOCATION storage keyword is not inherited.

The following tables show the indices and locations for Sample.Person and Sample.Employee. Notice the last index in the Sample.Employee table:

Any generated global index locations and EXTENTLOCATION are updated back into the active storage definition after the class is compiled.

If USEEXTENTSET is FALSE, then global names are generated using the package-hash.class-hashSuffix strategy. For example, ^Sample.PersonD and ^Sample.PersonI("SSNKey") are globals used by Sample.Person and specific index structures are all stored in ^Sample.PersonI with the index name used as the first subscript.

WARNING!! This is a destructive call.

Drop all Databases defined in the current namespace. User data is deleted.

WARNING!! This is a destructive call.

Drop the Database and remove its extent. User data is deleted.

Retrieve documents that match the restrictionRequest restriction. The set of properties included in the result is defined by projectionRequest. Find options can be specified in the optionsRequest argument. The format of these arguments is either a %DynamicAbstractObject oref or a string containing JSON.

restrictionRequest - This can be either a predicate or an array of predicates. A predicate is an array with three elements, the first is the property to be restricted, the second is the value the property is compared to and an optional third element is the comparison operator. The comparison operator defaults to "=". The list of supported comparison operators includes =, !=, <, >, <=, >=, <>, %STARTSWITH, IN, NULL, and NOT NULL. When multiple predicates are specified they are combined using AND. Properties included in the restriction must be defined in the Database.

projectionRequest - an array of properties to select from the Database. If not specified then the projection will include %DocumentId, %LastModified and %Doc. The properties included in the projectionRequest must be explicitly defined in the Database.

optionsRequest - is an object containing the requested options. At this time, the only option supported is limit. If options.limit is specified then it is the maximum number of matching documents retrieved from the database.

The return value is a %Library.DynamicArray whose elements correspond to objects as defined by projectionRequest.

	SAMPLES>set result = db.%FindDocuments(["Name","N","%STARTSWITH"],["Name"],{"limit":5})             

	SAMPLES>w result.%ToJSON()                                                                          
	{"sqlcode":100,"message":null,"content":[{"Name":"Nebraska"},{"Name":"Nevada"},{"Name":"New Hampshire"},{"Name":"New Jersey"},{"Name":"New Mexico"}]}

%FromJSON() - accepts a stream, a string containing JSON, a stream oref or a string containing a file URI. The contents of jsonValue are then inserted into the current database. This method return an oref referencing the database to support stringing method calls.

If a file URI is passed then a file stream is instantiated and the translation table set to UTF-8. If the file is not encoded as UTF-8 then the user must instantiate a stream object before calling $fromJSON() and set the translation table to the appropriate value.

SaveDocument() accepts a document value and an optional documentID. The document value is either an instance of the DocumentType class or a serialized value in the format expected by the DocumentType class. The default serial format is JSON. If documentID is specified then the document identified by that value is replaced by the provided document value. If a document with that ID does not exist then an exception is thrown. If no documentID then the provided document value is inserted into the Database. This method returns the instance of the Database class that was inserted or replaced.

USER>set car = cars.%SaveDocument({"make":"Ford","model":"Flatbed","year":"1938","location":{"city":"Winslow","state":"Arizona"})

This method throws an exception if an error is encountered.

SaveDocumentByKey()

destination is optional. There are a number of possibilities:
(1) Parameter destination is not defined and the method is called via 'DO'. In this case the JSON string is written to the current output device.
(2) Parameter destination is not defined and the method is called as an expression. In this case the JSON string becomes the value of the expression.
(3) Parameter destination is defined. If it is %Stream object then the JSON string will be written to the stream. If destination is not an object and is not null then it is presumed to be a fully qualified file specification. In that case, a %Stream.FileCharacter stream is created, linked to that file and the JSON string is written to that stream. On completion, this stream is saved. The full path to the file must be defined. If destination is an object but is not an instance of %Stream.Object then an exception will be thrown.