VB ZOOM ActiveX Component 1.2c1.1

The following is a binding of the ZOOM 1.2 API to a Visual Basic ActiveX Component.

This software and documentation is licensed under the University of Illinois/NCSA Open Source License.

Object Model

• ZoomFactory
  • ZoomConnection
    • ZoomResultSet
      • ZoomRecord
    • ZoomScanSet
  • ZoomQuery

Errors

Options

Notes

Source Files

ZoomFactory

This object is used to create new instances of other objects, namely ZoomConnection and ZoomQuery objects.

This is GlobalMultiUse object, meaning that if a reference to the ActiveX DLL is added to a project, this classes methods and properties are accessible without explicitly creating an instance of this class. However, this object may be created using the New operator or the CreateObject method from Scripting environments. Its ProgID is 'VBZOOMC.ZoomFactory', and its VB Class Name is 'ZoomFactory'.

Properties

Class read-only

The name of this class 'ZoomFactory'

Z_PQF read-only

The integer (0) representing the Prefix Query Format used for the CreateZoomQuery method.

Methods

CreateZoomConnection([hostname], [portnum])

If successful this object returns an instance of a ZoomConnection object. The optional hostname parameter defaults to 'localhost', and the portnum parameter defaults to 210.

Note that creating the ZoomConnection object does not immediately establish the connection with the server. This is deferred until either a Search or Scan is performed. This allows various Options to be set prior to initalizing the connection and sending requests.

CreateZoomQuery(qry, [typ])

If successful this object returns an instance of a ZoomQuery object. The qry parameter is a string which represents the query. The optional type parameter is an integer indicating what type of query the qry string represents. It defaults to Z_PQF (0). Currently the only ZoomQueryType os Z_PQF (0) for the Prefix Query Format defined by the YAZ toolkit.

ZoomConnection

This object represents a connection to a particular Z39.50 server.

The only way to create an instance of this object is by the ZoomFactory.CreateZoomConnection method.

Properties

AdditionalInfo read-only

If the last request to the server resulted in additional information, this will return the Z39.50 additional information, if any.

Class read-only

The name of this class 'ZoomConnection'

ErrorCode read-only

If the last request to the server resulted in an error, this will return the Z39.50 error code which was returned. A non-zero return indicates an error in which case the ErrorMessage and AdditionalInfo properties can be used to return additional info about the error.

Normally, a Z39.50 error will cause an actual error to be raised by the system. However, if custom error handling or trapping is enabled, this property can be used to get the actual Z39.50 error which occurred, instead of the VB error that was thrown. See the section on Errors for more details.

ErrorMessage read-only

If the last request to the server resulted in an error, this will return the Z39.50 error message which was returned, if any.

Host read-only

Returns the host name or IP address of the Z39.50 server to which we are connected. Defaults to 'localhost'.

Port read-only

Returns the port number of the Z39.50 server to which we are connected. Defaults to 210.

Methods

GetOption(name)

Returns a particular named option associated with the connection. The name parameter is a string which is the name of the option. If the option has never been set either an empty string is returned or a default value. An attempt to get an unknown option will result in an error. See the section on Options for more details.

Scan(qry)

If successful, this method returns a ZoomScanSet object. The qry parameter is a string representing the term at which to start the scan.

Search(qry)

If successful, this method returns a ZoomResultSet object. The qry parameter is a ZoomQuery object which represent the search to be performed.

SetOption(name,value)

Sets a particular named option to a given value. The name parameter is a string which is the name of the option. The value parameter is a string for the value. This method will return whatever the previous value for the given option was. If the option had never been set either an empty string is returned or a default value. An attempt to set an unknown option will result in an error. See the section on Options for more details.

ZoomQuery

This object represents a Z39.50 search query.

The only way to create an instance of this object is by the ZoomFactory.CreateZoomQuery method.

Properties

Class read-only

The name of this class 'ZoomQuery'

QueryString read-only

The string used to create this particular query.

QueryType read-only

The type of the query used used to create this particular query. The only current valid value is Z_PQF (0) for the YAZ Prefix Query Format.

ZoomResultSet

This object represents Z39.50 search result.

The only way to create an instance of this object is by the ZoomConnection.Search method.

Properties

AdditionalInfo read-only

If the last request to the server resulted in additional information, this will return the Z39.50 additional information, if any.

Class read-only

The name of this class 'ZoomResultSet'

ErrorCode read-only

If the last request to the server resulted in an error, this will return the Z39.50 error code which was returned. A non-zero return indicates an error in which case the ErrorMessage and AdditionalInfo properties can be used to return additional info about the error.

Normally, a Z39.50 error will cause an actual error to be raised by the system. However, if custom error handling or trapping is enabled, this property can be used to get the actual Z39.50 error which occurred, instead of the VB error that was thrown. See the section on Errors for more details.

ErrorMessage read-only

If the last request to the server resulted in an error, this will return the Z39.50 error message which was returned, if any.

Methods

GetOption(name)

Returns a particular named option associated with result set. The name parameter is a string which is the name of the option. If the option has never been set either an empty string is returned or a default value. An attempt to get an unknown option will result in an error. See the section on Options for more details.

GetRecord(which)

Returns a ZoomRecord. The which parameter is the number of the record to return from 0 to GetSize-1.

GetSize()

Returns the total number of records associated with the result set.

SetOption(name,value)

Sets a particular named option to a given value. The name parameter is a string which is the name of the option. The value parameter is a string for the value. This method will return whatever the previous value for the given option was. If the option had never been set either an empty string is returned or a default value. An attempt to set an unknown option will result in an error. See the section on Options for more details.

ZoomScanSet

This object represents Z39.50 scan result.

The only way to create an instance of this object is by the ZoomConnection.Scan method.

Properties

AdditionalInfo read-only

If the last request to the server resulted in additional information, this will return the Z39.50 additional information, if any.

Class read-only

The name of this class 'ZoomScanSet'

ErrorCode read-only

If the last request to the server resulted in an error, this will return the Z39.50 error code which was returned. A non-zero return indicates an error in which case the ErrorMessage and AdditionalInfo properties can be used to return additional info about the error.

Normally, a Z39.50 error will cause an actual error to be raised by the system. However, if custom error handling or trapping is enabled, this property can be used to get the actual Z39.50 error which occurred, instead of the VB error that was thrown. See the section on Errors for more details.

ErrorMessage read-only

If the last request to the server resulted in an error, this will return the Z39.50 error message which was returned, if any.

Methods

GetField(which, field)

Return a string which is the value of a particulat scan field. The which parameter is the number of the scan record from 0 to GetSize-1. The field parameter is a string which is the name of the field to return. Acceptible values for field are:

• freq - the number of occurrences of the term
• display - the display value for the term (currently always returns just the term)
• attrs - TODO: always returns an empty string
• alt - TODO: always returns an empty string
• other - TODO: always returns an empty string

Any other value for field results in an error.

GetOption(name)

Returns a particular named option associated with scan set. The name parameter is a string which is the name of the option. If the option has never been set either an empty string is returned or a default value. An attempt to get an unknown option will result in an error. See the section on Options for more details.

GetSize()

Returns the total number of terms associated with the scan set.

GetTerm(which)

Return a string which is a particlar scan term. The which parameter is the number of the scan term to return from 0 to GetSize-1.

SetOption(name,value)

Sets a particular named option to a given value. The name parameter is a string which is the name of the option. The value parameter is a string for the value. This method will return whatever the previous value for the given option was. If the option had never been set either an empty string is returned or a default value. An attempt to set an unknown option will result in an error. See the section on Options for more details.

ZoomRecord

This object represents a record returned by a Z39.50 search.

The only way to create an instance of this object is by the ZoomResultSet.GetRecord method.

Properties

Class read-only

The name of this class 'ZoomRecord'

Database read-only ZOOM Extension

Returns a string containing the name of the database containing the record

RawData([type]) read-only

Returns the raw data for the record in various data types depending on the value of the type parameter. The optional type parameter is an enumeration of types suggesting how the raw data should be returned. The possible values are:

RawDataDefault (0)

This is the default if type is not specified. In this case, the type of data returned depends on the record syntax. For octet aligned syntaxes, such as SUTRS or MARC, the returned data will be a RawDataString (vbString). For other record syntaxes, such as GRS-1, the returned type will be a RawDataPointer (vbLong) which is a pointer to a YAZ Z_External struct.

RawDataString (vbString = 8)

For octet aligned syntaxes, such as SUTRS or MARC, the returned data will be a variant string (vbString).

RawDataByteArray (vbByte + vbArray = 17 + 8192 = 8209 )

For octet aligned syntaxes, such as SUTRS or MARC, the returned data will be a variant array of bytes (vbByte + vbArray).

RawDataPointer (vbLong = 3)

For octet-aligned record syntaxes, such as SUTRS or MARC, a variant long which is a pointer to the character buffer will be returned. For other record syntaxes, a pointer to a YAZ Z_External struct is returned. For non-octet aligned syntaxes, the RawDataPointer type is the only type which is ever returned; this is why type is only considered a suggestion.

This data type is mostly used internally, but it is provided for anyone interested in delving into the world of Win32 API programming, or working directly with the YAZ data structs. You cannot assume that octet buffers pointed to by this value are null terminated, so in some cases you will need to get the length before you can safely use the pointer (see the following RawDataLength value).

RawDataLength (-1)

Returns the length in bytes of the RawData, if it is known. If the length cannot be determined -1 is returned. This value is mostly only used internally, but it may be required for correctly processing RawDataPointers.

After the RawData property is returned, the type parameter (if any) will contain the actual data type returned. The return type can also be checked using the VB TypeName function, if desired.

NOTE: Caution should be exercised when dealing with the vbString data type returned from this property, especially when using various scripting languages, such a JScript or VBScript. The 8-bit character strings are automatically converted into 16-bit Unicode wide character strings and back again. This conversion often assumes the string is Windows 1252 (or even worse 1250 et al., depending on the locale setting of the machine) Characters in the range hex 80 to 9F (and possibly others as well) are converted into their Unicode equivalents. The problem is that this conversion may not be appropriate, depending on the original character encoding of the raw data. To prevent this from happening you should use the RawDataByteArray data type, and then convert the bytes into strings or other data types according to you own needs. More details on this issue can be found under this Bug Report on SourceForge.

XMLData read-only ZOOM Extension

Returns an XML DOMDocument40 object for the record in its XML format. This property is supported for the following record syntaxes:

USmarc

The XML returned will conform to the MARC 21 XML Schema, maintained by the Library of Congress. The 'marc:' prefix has been bound to the namespace for the MARC 21 XML schema. Therefore, when referring to elements using XPath expression, remember to use the prefix, for example: //marc:datafield[@tag='245']

text-XML, XML, or application-XML

The XML string returned by the server is loaded into the DOM. The schema can vary.

OPAC

The XML returned will conform (roughly) to the XML Encoding Rules for ASN.1. If MARC is used for the bibligraphicRecord portion of the OPAC, then the MARC 21 XML Schema, maintained by the Library of Congress will be used in that section; likewise, if MARC is used for the holdingsData. The 'marc:' prefix has been bound to the namespace for the MARC 21 XML schema. Therefore, when referring to MARC elements using XPath expression, remember to use the prefix, for example: //marc:datafield[@tag='245']. No namespace is used for the base XER elements for the OPAC record, so no namespace prefix is required.

Currently, accessing this property for any other record syntaxes will result in an error. If the XML is not well-formed an error will also be raised.

Also note that the XML will not be validated even if the XML contains a reference to a DTD or Schema. If desired, you can validate the XML via the DOMDocument.validate() method.

Methods

GetField(spec, [opt])

Returns a string containing the data from a particular record field. The spec parameter is a string used to specify which field to return. The spec syntax varies according to the record syntax. The opt parameter is optional. It may contain data required to further qualify the spec. It is currently only used for XML record syntaxes to bind prefixes to namespaces for use in XPath expressions. The record syntaxes currently supported and the spec syntax are described below:

USmarc

spec	::=	MARCPath | XPath
MARCPath	::=	leader['/'range] | controltag['/'range] | datatag['$'code['/'range]]
leader	::=	000
controlTag	::=	00[1-9]
dataTag	::=	(0[1-9][0-9]|[1-9][0-9][0-9])
range	::=	(\d+|\d+\-\d+)
code	::=	[\da-z!"#$%&'()*+,-./:;<=>?{}_^`~\[\]\\]
XPath	::=	<Any string not starting with a digit will be interpretted as an XPath expression against the MARC 21 XML version of the record. All element names must use the 'marc:' prefix to specify the correct namespace.>

MARCPath Examples: 000 - returns the marc leader; 008 - returns the complete 008 field; 008/6 - returns the 7th character of the 008 field; 245 - returns the complete 245 field; 245$a - returns the $a subfields of the 245 field; 245$a/0-9 - returns the first 10 characters of the $a subfields of the 245 field.

If a MARCPath expression is used for the spec, the format of the returned field is: 'tag[/range] [indicators] fields', for example:

245 10 $a Some issues ...
008/0-5 990817

If there are multiples of a given field, each will be returned spearated by a Cr/Lf.

XPath Examples: /marc:record/marc:controlfield[@tag='008'] - returns the complete 008 field; /marc:record/marc:datafield[@tag='245']/marc:subfield[@code='a'] - returns the $a subfields of the 245 field.

If an XPath expression is used for the spec, an XML fragment string from the MARC XML will be returned, such as <controlfield tag='008'>...</controlfield>. Note that this will only be an XML fragment and may not be well-formed.

text-XML, XML, or application-XML

For all XML syntaxes, the spec will be interpreted as an XPath expression. The optional opt parameter is used to bind prefixes to namespaces for the XPath expression, for example:

field = GetField("//marc:datafield[@tag='245']", "xmlns:marc='http://www.loc.gov/MARC21/slim'")

OPAC

OPAC is converted to the XML Encoding, as previously described for the XMLData property, so XPath expressions may be used to query for specific fields, just as for XML. The optional opt parameter is used to bind prefixes to namespaces for the XPath expression. However, this shouldn't normally be required as the XML does not use namespaces for the base elements, and the marc prefix has already been bound in case any of the OPAC elements contained embedded MARC.

If there is no field which matches the given spec, an empty string is returned. If the GetField methods is used for an unsupported record syntax an error is raised.

GetNumberOfFields()

Return the number of individual fields contained in the record. The number of fields depends on the record syntax as described below:

USmarc:	the total number of control fields plus the number of subfields in each data field, plus one for the MARC leader. See the GetField method for details.
text-XML: XML: application-XML:	the total number of element nodes in the XML, including the root element and all children, grandchildren, etc.
OPAC:	since OPAC is reprtesented as XML, the total number of element nodes in the XML, including the root element and all children, grandchildren, etc.

If the number of fields is unknown, -1 is returned.

GetRecordSyntax()

Return a string which is the name of the native record syntax for this record, such as 'USmarc', 'XML', or 'SUTRS'

RenderRecord()

Returns a string containing the record which has been marginally rendered for human consumption. If a record syntaxes has no convenient rendering an empty string is returned. For OPAC records a string containing the XML rendering is returned. For other record syntaxes, whatever string YAZ returns is used.

Errors

Invalid query type 'type' [-2147221303]

An attempt has been made to create a ZoomQuery using an invalid type parameter.

ZOOM Error ErrorCode: ErrorMessage (AdditionalInfo) [-2147221302]

A Z39.50 server has returned an error in response to the most resent request.

Invalid query 'querystring' [-2147221301]

An attempt has been made to create a ZoomQuery using an invalid querystring parameter.

No record at position position [-2147221300]

An attempt has been made to access a record that doesn't exist at the given position

'optionname' not a valid option name [-2147221299]

An attempt has been made to get or set an option which is not valid

'fieldname' not a valid scan field [-2147221298]

An attempt has been made to access a scan field which is not valid

'spec' not a valid field specification [-2147221297]

The spec parameter used for the GetField method is not valid

This method not supported for 'syntax' records [-2147221296]

An attempt was made to use the GetField method on an unsupported record syntax

Internal Error: errorMsg [-2147221295]

Something unexpected happened; errorMsg will usually explain what and/or where, so you can report back to the developers.

Unknown character encoding 'encoding' [-2147221294]

An unknown character encoding indicator was found in the MARC leader. Currently, only 'a' for UTF-8 Unicode and ' ' for MARC-8 are supported.

'number' is not a supported raw data type [-2147221293]

An unknown data type was requested for the RawData.

MARC record is missing the record terminator [-2147221273]

The syntax of the MARC record does not appear to be valid, or the record does not follow the Z39.2-1994 standard.

MARC record directory is missing the field terminator [-2147221272]

The syntax of the MARC record does not appear to be valid, or the record does not follow the Z39.2-1994 standard.

MARC record has an invalid entry map [-2147221271]

The syntax of the MARC record does not appear to be valid, or the record does not follow the Z39.2-1994 standard.

MARC record variable field is missing field terminator [-2147221271]

The syntax of the MARC record does not appear to be valid, or the record does not follow the Z39.2-1994 standard.

MARC record missing control number [-2147221270]

The syntax of the MARC record does not appear to be valid, or the record does not follow the Z39.2-1994 standard. All MARC records should have an 001 field, but this record does not.

XML Error code: (line:pos) reason [-2147221269]

The XML parser has encountered an error

MARCFactory is not initialized (usually because of unsupported character encoding) [-2147221268]

An attempt was made to access some property of an unitialized MARCRecord. A MARCRecord may be unitialized because of programmer error :-), or because the MARC contained an unsupported character encoding.

MARC XML is not well-formed [-2147221267]

Something unexpected happened while trying to parse the MARC XML.

MARC record contained implementation defined data 'data' in a variable data field [-2147221266]

Even though the Z39.2-1994 standard supports an implementation defined region inside of data fields, the MARC 21 standard does not.

MARC only supports 2 indicators per data field; number were found [-2147221265]

Even though the Z39.2-1994 standard supports an arbitrary number of indicators per data field, the MARC 21 standard requires exactly two.

MARC Leader is invalid [-2147221264]

The MARC leader (first 24 bytes of record) appears to be corrupt, preventing any further parsing.

WIN32 API Error: details [-2147221247]

An unexpected error value was returned by a Win32 API function.

The MSXML 4.0 parser does not appear to be installed [-2147221246]

The MSXML 4.0 parser is required, but it does not appear to be installed on the machine.

Warnings

These warning conditions are currently just ignored, but in future versions it will be possible to extract these warnings from the objects.

Unknown character encoding 'encoding' [110]

An unknown character encoding indicator was found in the MARC leader. Currently, only 'a' for UTF-8 Unicode and ' ' for MARC-8 are supported. If an unknown encoding is found, MARC-8 will be assumed.

MARC record variable field is missing field terminator [134]

The syntax of the MARC record does not appear to be valid, or the record does not follow the Z39.2-1994 standard. A record terminator seems to have been used instead of the expected field terminator.

MARC record missing control number [135]

The syntax of the MARC record does not appear to be valid, or the record does not follow the Z39.2-1994 standard. All MARC records should have an 001 field, but this record does not.

Invalid character chr(number) found at position position and replaced with 'string' [700]

A character which is not valid within a MARC record was encountered. It was replaced with a string "" which is valid.

'character' is not a valid value for the Leader, Entry Map, Length of implementation-defined field; using 0 [701]

An unexpected character was found in the Leader, Entry Map, or Length of implementation-defined field. It is being replaced with the '0' character.

Options

The supported options are exactly those supported by the ZOOM functions of the YAZ Toolkit from Index Data. Refer directly to the Z39.50 specifications for additional details on these options.