library

Top  Previous  Next

library

o=new("library",libname$[,create])

 

The library object provides extensive access to the documents in a specific library, specified in libname$, including document listings and manipulation of individual document and sub-image properties, as well as general library information.  If the libname$ provided is not found, a new library is created if the create field is true (1).

 

The library object enforces library security, and will generate appropriate errors if the active user login (specified with the setlogin() code block function) does not have rights to perform requested operations.  Note that secure passwords can be configured in the browser interface and referenced in the setlogin() function.

 

Properties

 

All properties are read-only.

 

datecreated$ is the date the library was created, in yyyymmdd format.

forceseq is true (1) if sub IDs are auto-sequenced to prevent overwriting.

inactive is true (1) if the library is locked from further updates.

lasterrmsg$ contains the last known error message related to methods.

libname$ is the name supplied to the object.

pathname$ is the full system path to the library.

permission$ is the default permission setting for users that do not have specific permissions allocated.  It is a semicolon-delimited list of "r", "w", or "d".

title$ is the library title, or description.

 

Methods

candelete(userid$) returns true (1) if the specified user can delete images or documents from the library.

canread(userid$) returns true (1) if the specified user can read the library.

canwrite(userid$) returns true (1) if the specified user can write to the library.

catcount() returns the number of category indexes in the library.

copydoc(doctype$,docid$,todoctype$,todocid$[,library$,[overwrite[,toobject]]]) copies a document, indentified by doctype$ and docid$, including all its subdocuments, to the specified todoctype$ and todocid$.  If library$ is specified, the document is copied to a different library.  Returns 1 if successful.  Returns 0, and fills lasterrmsg$, if not.  The overwrite flag can be 0 to skip duplicates, 1 to overwrite duplicates (removes target first), 2 to compare update dates before replacing document and sub ID records, and 3 to do a full merge of properties and sub ID's.  Note that unlike version 8.0, to overwrite a document when using this method, the overwrite flag must be supplied.

 

If you will be copying a number of documents to the same library, you can create a library object for the target library, and supply that object in as the toobject value.  Otherwise, a new target library object is created and destroyed for each copy operation.

copysubdoc(doctype$,docid$,subid$,todoctype$,todocid$,tosubid$[,library$]) copies a subdocument, indentified by doctype$, docid$, and subid$, including its image data, to the specified todoctype$, todocid$, and tosubid$.  If library$ is specified, the subdocument is copied to a different library.  Returns 1 if successful.  Returns 0, and fills lasterrmsg$, if not.

countcats([seed$]) returns the number of category indexes within the given seed.  If no seed$ is provided, a count of initial segments is returned.  If seed$ is provided, the count is the number of segments at the next level.  Seed$ is pipe-delimited.  For example, countcats("Customers|ByName") would return the number of third-level segments within Customers|ByName.

countdocs(doctype$[,idseed$]) returns the number of documents in the specified document type.  If an ID seed is provided, the count only includes doc ID's that start with the seed.

countdocsbycat(seed$) returns the number of documents for the specified category index, which is in a pipe-delimited segment series format.

countdocsbydate(date$) returns the number of documents for the specified date.  Date$ should be in yyyymmdd format.

countdocsbykeyword(keyword$) returns the number of documents indexed by the keyword specified.

countdocsbytypedate(type$,date$) returns the number of documents for the specified type and date.  Date should be in yyyymmdd format.

countdocsbytypeupdated(type$,date$) returns the number of documents for the specified type and updated date.  Date should be in yyyymmdd format.

countdocsbyupdated(date$) returns the number of documents for the specified updated date.  Date$ should be in yyyymmdd format.

countdocsbyentity(entityid$) returns the number of documents for the given entity ID.

delcategory(doctype$,docid$,segs$) removes the category segment defined in segs$ from the document.  The segs$ value is a pipe-delimited list of category segments.  The value is removed from the categories property and from the category index file.

deldoc(doctype$,docid$) removes the specified document, and any of the document's sub IDs , from the library.

deldocdata(doctype$,docid$,name$) removes the docdata item name$ from the document doctype$, docid$.

delkeyword(doctype$,docid$,keyword$) removes the keyword and its index from the specified document.

dellink(doctype$,docid$,link$) removes the link string from the specified document.  LInk strings can be urls, or pipe-delimited values of three or four values indicating library, doctype, docid, and optional subid.

delsubdoc(doctype$,docid$,subid$) removes the specified subdocument from the library.

doccount() returns the number of documents in the library.

docdatacount() returns the number of document data records are in the library.

docdataexists(doctype$,docid$,name$) returns true (1) if the docdata item name$ is found in document doctype$, docid$.

docexists(doctype$,docid$) returns true (1) if the document type and ID exist in the library, false (0) otherwise.

getcats$([seed$[,first|first$[,count[,descending]]]]) returns a linefeed delimited list of category indexes found in the library.  Each index has pipe (|) segment delimiters.  If seed$ is provided, the list is returned within the prefix found in seed$, which is a pipe-delimited list of segments.  In this way, it is possible to get a list of indexes, sub-indexes, sub-sub-indexes, and so forth.  The list starts at the record number specified by first, or the sub-segment value specified in first$.  Up to count records are returned.  If descending is true (1), the list produced in descending order.

 

getcats$() returns a list of initial category segments.

 

getcats$("Customers") returns a list of second segments within the "Customers" initial segment.

 

getcats$("Customers|ByName","B",1000) returns a list of up to 1000 category indexes within the Customers, ByName seed, listing values of the third segment, starting with "B".

getcatsbyprefix$(seed$,prefix$,first,count) returns a linefeed delimited list of category segments for the given category seed$ and starting value. The list starts at first record, for count records.  The seed value is a pipe-delimited list of segments that preceed the desired segment the list is generated from.  The prefix$ value is the starting value of the desired segment, used to seed the starting point of that segment.

getcattypes$(seed$) returns a linefeed delimited list of document types for the given category index, specified by the a pipe-delimited list of category segments.

getdates$([type$,][year[,month]]) returns a linefeed delimited list of document dates found in the library.  Dates are returned in yyyymmdd format.  If the year, or year and month, are provided, only dates for that period are returned.  If type$ is supplied, then dates within that document type are returned.

getdoc(doctype$,docid$,doc$) fills the doc$ property template with document properties, and returns 1 if successful.  The template contains the following fields:

doctype$
docid$
date$ (yyyymmdd)
time$ (hhmmss)
dateupdated$
timeupdated$
title$
entityid$
notes$
keywords$
categories$
links$

getdocdata(doctype$,docid$,name$,value$) fills value$ with the docdata value for name$, for the document doctype$, docid$.

getdocdatanames$([first,count]) returns a list of document data names found in the library, either all names or the range specified.

getdocdata$(doctype$,docid$[,name$]) returns a tab-separated-values list of document data names and values for the specified document.  If name$ is supplied, the returned value is instead just the value of that docdata item.  Name$ is not case sensitive.

getimage(doctype$,docid$,subid$,filename$) extracts the image data to the specified filename$.  If filename$ is null, then a temporary file is generated with an appropriate extension and returned in filename$.  The temporary file is automatically deleted with the job is complete.  A user-supplied file name is not deleted.  Returns 1 if successful.  If not successful, lasterrmsg$ will contain an error message.

getkeywords$([seed$,]first,count) returns a list of count keywords, starting with index first.  If seed$ is provided, keywords must start with the seed value.  Keywords are case-insensitive.

getkeywordseeds$([prefix$,]length) returns a list of unique keyword prefixes, up to length+1 characters.  If prefix$ is supplied, only keyword prefixes starting with that value are returned.  Keyword seeds are not keywords themselves, but keywords prefixes.  Base keywords prefixes, with no prefix$ and a length of 1, would be a list of 1-character values that start all keywords (i.e. a, b, d, 0, 1, etc.).

getrange$(doctype$,first|first$,count[,descending[,delim$[,skip]]]) returns a linefeed delimited list of document types and IDs within the specified document type.  The list starts at the record number specified by first, or the document ID specified by first$.  Up to count records are returned.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type and ID are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).  If skip is specified, that many records are skipped before starting the list.

 

An addition argument structure limits the list to a document type and ID values starting with a seed value.

 

getrange$(doctype$,first,count,descending,delim$,idseed$)

 

getrange$(first,count[,order[,descending[,delim$]]]) returns a linefeed ($0A$) delimited list of document types and IDs.  The list range is in sequence based on the value of order: 0=type/ID, 1=date/time created, 2=title.  The range is specified with first and count, indicating the starting document, and the maximum number to return.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type and ID are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).

getrangebycat$(seed$,first,count[,descending[,delim$]]) returns a linefeed delimited list of document types, IDs, and category indexes, in category index order, within the specified seed, which is provided as pipe-delimited segments.  The list starts at the record number specified by first.  Up to count records are returned.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type, ID, and category index are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).

getrangebydate$(date$,first|first$,count[,descending[,delim$]]) returns a linefeed delimited list of document types, IDs, and date/times, in date/time sequence, within the specified date, which is provided in yyyymmdd format.  The list starts at the record number specified by first, or the time specified by first$ (in hhmmss format, 24 hour clock).  Up to count records are returned.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type, ID, and date/time are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).

getrangebydocdata$(name$[,first[,count,[justvalues]]]) returns a tab-separated-values list of doctype, docid, and docdata values for the given docdata name.  The first and count values are used to get a range of records.  If justvalues is true (non-0) then a range of values for the specified name, from the whole library, is returned.

getrangebydocdata$(name$,value$[,first[,count]]) returns a tab-separated-values list of doctype and docids for the given docdata name and value.  The first and count values are used to get a range of records.

getrangebyentity$(entityid$,first,count[,descending[,delim$]]) returns a linefeed delimited list of document types and IDs for the given entity ID.  The list starts at the record number specified by first.  Up to count records are returned.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type, ID, and category index are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).

getrangebykeyword$(keyword$[,first,count]) returns a list of document types and IDs for the given keyword.  If first and count are supplied, count records are returned, starting with index first.

getrangebytypedate$(type$,date$,first,count[,descending[,delim$]]) returns a linefeed delimited list of document types, IDs, and date/times, in type and date/time sequence, within the document type and specified date, which is provided in yyyymmdd format.  The list starts at the record number specified by first. Up to count records are returned.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type, ID, and date/time are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).

getrangebytypeupdated$(type$,date$,first,count[,descending[,delim$]]) returns a linefeed delimited list of document types, IDs, and updated date/times, in type and last updated date/time sequence, within the document type and specified date, which is provided in yyyymmdd format.  The list starts at the record number specified by first. Up to count records are returned.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type, ID, and date/time are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).

getrangebyupdated$(date$,first|first$,count[,descending[,delim$]]) returns a linefeed delimited list of document types, IDs, and updated date/times, in last updated date/time sequence, within the specified date, which is provided in yyyymmdd format.  The list starts at the record number specified by first, or the time specified by first$ (in hhmmss format, 24 hour clock).  Up to count records are returned.  If descending is true (1), then the list is returned in descending order.  If delim$ is specified, the type, ID, and date/time are delimited by that character.  If no delim$ is specified, then they are delimited by a tab ($09$).

getrecentdates$([type$,]count) returns a linefeed delimited list of the most recent dates in the library. The count value specifieds the number of dates to return.  Dates are returned in yyyymmdd format.  If type$ is supplied, then dates within that document type are returned.

getrecentupdated$([type$,]count) returns a linefeed delimited list of the most recent updated dates in the library. The count value specifieds the number of dates to return.  Dates are returned in yyyymmdd format.  If type$ is supplied, then dates within that document type are returned.

getsubdoc(doctype$,docid$,subid$,subdoc$) fills the subdoc$ property template with subdocument properties, and returns a 1 if successful.  You can reference properties as subdoc.doctype$, subdoc.docid$, subdoc,subid$,subdoc.title$, subdoc.date$, subdoc.time$, subdoc.type$, subdoc.notes$, and subdoc.size.  The subid value can end in "-<" or "->" to return the first or last sub ID records, respectively, given a starting seed value that precedes the -< or -> sequence.  For example scan-> will return the last sequence of sub ID values that start with "scan".

getsubids$(doctype$,docid$[,notext[,currentid$[,withdata]]]) returns a linefeed ($0A$) delimited list of sub IDs on file for the given document.  If notext is true (non-zero), don't return @text* subids.  If currentid$ is provided, don't return that id.  If withdata is provided, a value of 1 returns a space delimited set of data for each, and if 2, returns a tab-delimited set of data for each.  The detail is subid, title, date, type, and notes, where notes white space is normalized to spaces.

gettypes$() returns a linefeed delimited list of document types found in the library.

getupdated$([type$,][year[,month]]) returns a linefeed delimited list of document update dates found in the library.  Dates are returned in yyyymmdd format.  If the year, or year and month, are provided, only dates for that period are returned.  If type$ is supplied, then dates within that document type are returned.

getyears$([withmonths[,updated]]) returns a linefeed delimited list of years found in the library.  If withmonths is true (1), years and months are returned, and if updated is true, the list is based on the last updated dates.

imgcount() returns the number of images (sub IDs) in the library.

kwcount() returns the number of keywords in the library.

movenext(doctype$,docid$[,docprop$]) returns information about the next document in sequence.  Doctype$, docid$, and if supplied, the docprop$ document properties template, are filled.  See the getdoc() method for information about fields in docprop$.  The method returns 1 if successful, or 0 otherwise (such as an end of file error).  The starting position of a series of move commands can be set with the moveto() method.

movenextcat(categories$,doctype$,docid$[,docprop$]) returns information about the next category and its associated document in sequence.  Categories$, doctype$, docid$, and if supplied, the docprop$ document properties template, are filled.  Categories$ is filled with a pipe-delimited list of category segments (note this is case-sensitive, returning segments as stored).  See the getdoc() method for information about fields in docprop$.  The method returns 1 if successful, or 0 otherwise (such as an end of file error).  The starting position of a series of category move commands can be set with the movetocat() method.

moveprev(doctype$,docid$[,docprop$]) returns information about the previous document in sequence.  Doctype$, docid$, and if supplied, the docprop$ document properties template, are filled.  See the getdoc() method for information about fields in docprop$.  The method returns 1 if successful, or 0 otherwise (such as an end of file error).  The starting position of a series of move commands can be set with the moveto() method.

moveprevcat(categories$,doctype$,docid$[,docprop$]) returns information about the previous category and its associated document in sequence.  Categories$, doctype$, docid$, and if supplied, the docprop$ document properties template, are filled.  Categories$ is filled with a pipe-delimited list of category segments (note this is case-sensitive, returning segments as stored).  See the getdoc() method for information about fields in docprop$.  The method returns 1 if successful, or 0 otherwise (such as an end of file error).  The starting position of a series of category move commands can be set with the movetocat() method.

moveto(doctype$[,docid$) seeds the next movenext or moveprev methods to the position specified by doctype$ and docid$.  To seed to the start of the library, provide a doctype$ of null.  To seed to the end, provide a high doctype$, such as $ff$.  Likewise, to seed to the end of a given document type, seed the docid$ with a high value like $ff$.

movetodate(ymd$[,hms$]) seeds the next movenext or moveprev to navigate the library in date/time order, beginning at the supplied date and optional time.  The date must be in yyyymmdd format, such as "20091231".  If the time is supplied, it must be in hhmmss format using a 24-hour clock, such as "150000" for 3:00 PM.

movetocat(seed$) seeds the next movenextcat or moveprevcat methods to an index position.  Seed$ must be provided as a series of pipe-delimited category segments, such as "Vendors|000999|PurchaseOrders".

newdoc(doc$) fills an empty document property template as doc$.  The property template fields are named  in the getdoc method, above.

newsubdoc(subdoc$) fills an empty subdoc property template as subdoc$.    The property template fields  are named in the getsubdoc method, above.

putcategory(doctype$,docid$,segs$) updates the category index specified in segs$, which must be a pipe-delimited list of segments for a single category index.  Note there can be more than one set of category segments per document, but this  method is used to update a single segment set.  The categories property is updated, as well as the category index file.

putdoc(doctype$,docid$,doc$ [,retainupdated) updates the specified document properties.  If the document does not exist, it will be added.  Note that this method does not add any image files to the library.  The doc$ template contains properties described in the getdoc method.  The doctype$ and docid$ values override the type/id values in the doc$ properties template.  If docid$ is null, it is assigned an automatic date-sequence ID value.  If retainupdated is true (provided and non-0), and the dateupdated$ property is not null, date and time updated values are retained.

putdocdata(doctype$,docid$,name$,value$) updates the specified docdata name$ with value$ for the document doctype$, docid$.

putkeyword(doctype$,docid$,keyword$) adds the keyword and its index to the document specified.

putlink(doctype$,docid$,link$) adds the link string to the specfied document. LInk strings can be urls, or pipe-delimited values of three or four values indicating library, doctype, docid, and optional subid.  Link strings can contain references to names in the uf100d.ini [linksubs] section, using square brackets, such as "[myserver]/doc/1000/index.html", which at view time would replace "[myserver]" with the value of myserver=value in [linksubs].

putsubdoc(doctype$,docid$,subid$,subdoc$[,filename$]) updates subdocument properties, and updates the image file as well, if filename$ is supplied.  If the specified subdocument does not exist, it is added. The subdoc$ template contains properties as described in the getsubdoc method.  The title, date, and time can be updated; other properties are ignored.  Note that if you set the date and time values to null (""), they will be updated with the current date and time.

subdocexists(doctype$,docid$,subid$) returns true (1) if the document type, ID, and sub ID exist in the library, false (0) otherwise.