BULK RETRIEVE API

A BULK RETRIEV request provides for a single function call that performs all of the required actions to generate the retrieval of multiple documents. A query is specified in the BR-SQL parameter. The hit list associated with a query is placed in the HFS file pointed to by the BR-FListName parameter. The documents retrieved for the hit list are placed in the HFS file pointed to by the BR-ThreadDir parameter. Up to 10 sets of values can be specified for these three parameters.

You need to delete previous hit lists and documents stored by the Bulk Retrieve API into the directories specified in the BR-FListNames and BR-ThreadDir parameters before each execution of Bulk Retrieve. If multiple Bulk Retrieves are to be run concurrently, each must specify unique directories.

The Bulk Retrieve function can be multi-threaded. For each different value specified in the BR-ThreadDir parameter, a new thread is created. All queries associated with the same BR-ThreadDir parameter value are run under the same thread.

The BR-NumSQL parameter controls how many sets of values are specified for the BR-FListName, BR-ThreadDir, and BR-SQL parameters. The BR-NumThread parameter identifies how many different values are specified for the BR-ThreadDir parameters.

The documents returned in the HFS file or files specified in the BR-ThreadDir parameters must be parsed to reconstruct the documents. If the document was stored with fixed length records, then that record length value must be used to parse the records in the hfs file. If the document was stored with variable length records, then each logical record in the hfs physical records is preceded by a two-byte length value. This length value can be used to parse the document records.

The fields described in Table 1 must be specified by the customer application in the CS-CommonStructure and BR-BulkRetrieveStructure fields before issuing the BULK RETRIEV function request.

Table 1. CS-CommonStructure and BR-BulkRetrieveStructure fields for BULK RETRIEV function
Field	Description	Required or optional?
CS-Eyeball	Common Structure Eyeball value of ARSLSCCO.	Required
CS-Length	Length of the CS-CommonStructure.	Required
CS-APILevel	CS-APILevel API level value of 8.4.	Required
CS-Request	Function request value of BULK RETRIEV.	Required
CS-MidTierIPAddr	TCP/IP address for the mid-tier server. The 'Host Name' representation of the TCP/IP address is supported in all environments.	Required
CS-MidTierPort	TCP/IP port number for the mid-tier server.	Required
CS-LibServIPAddr	TCP/IP address for the Content Manager OnDemand library server. The 'Host Name' representation of the TCP/IP address is supported in all environments.	Required
CS-LibServPort	TCP/IP port number for the library server.	Required
CS-CodePage	The Content Manager OnDemand Server code page. Default value is 500. Important: The API does not edit this field for valid code page values.	Required
CS-FolderName	A full folder name; returns only the folder specified.	Required
CS-APITraceLevel	Trace flag: 0 No trace 1 Summary tracing 2 Full trace	Required
CS-SocketsRequested	Number of sockets requested. If unspecified, blank, or less than 100, the default is 1200.	Optional
CS-NumSec-to-Wait	A non-zero number that is entered to specify the wait time for a send/receive request to complete. The default is 300 seconds. Important: After a non-zero value is specified, it remains in effect for all subsequent API requests until a new value is specified.	Optional
Bulk Retrieve Structured Fields
BR-Eyeball	Logon Structure Eyeball value of ARSZSCBR.	Required
BR-Length	Length of the BR-BulkRetrieveStructure.	Required
BR-UserID	Content Manager OnDemand user ID. The user ID provided must match a user defined in the Content Manager OnDemand server database for the user ID in field LO-UserID.	Required
BR-Password	User password. The password must match the password for the user defined in the Content Manager OnDemand server database for the user ID in field LO-UserID.	Required
BR-AG	Application group name.	Required
BR-Language	Language. Default is en.	Optional
BR-Country	Country code. Default is US.	Optional
BR-MaxHits	Maximum number of hits to be returned by SQL.	Required
BR-DiskW	0 Write retrieved document data directly to disk. Uses less memory and is slightly faster, but the program fails if the same document (document name) is retrieved twice on the same thread or the same directory. BR-DiskW can be used only if all document names on a thread or in a directory are unique. 1 Retrieves document data in memory, then writes the file (document data) to disk. Uses more memory and is slightly slower. This option overwrites existing files if they already exist; thus, if the same file (file name) is downloaded 10 times (on the same thread) only one copy remains in the designated directory.	Required
BR-Debug	Debugging parameters: 0 No debug statements 1 Print thread statistics summary 2 Print thread statistics detail 3 Print configuration file values that are read 4 Echo SQL arrays that are read from the configuration file 5 Print thread startup values (in main) 6 General debug ArsBulkRetrieve class 7 Debug document retrieval Each higher debug level includes debugging statements from all lower levels.	Required
BR-SQLSec	Wait time between thread startups.	Required
BR-NumThread	The number of threads. An integer between 1 and 10.	Required
BR-NumSQL	The number of SQL statements to be executed.	Required
The structure contains locations for 10 of each of the following three fields. The number of entries that will be read is equal to the BR-NumSQL value.
BR-FListName	File name that will contain a list of the files retrieved by the SQL statement. There is one entry for each SQL statement. If BR-NumSQL is n, then there must be n entries, one file per thread.	Required
BR-ThreadDir	The directory containing the output when a SQL statement is executed by a thread. There is one entry for each SQL statement. If BR-NumSQL is n, there must be n entries. SQL statements with the same directory name execute under the same thread.	Required
BR-SQL	SQL statement to be executed. There is one entry for each SQL statement. If BR-NumSQL is n, there must be n entries.	Required

Table 2 describes the fields that are returned from the Content Manager OnDemand server following the BULK RETRIEV request. The fields are provided in the CS-CommonStructure.

Table 2. CS-CommonStructure fields returned by BULK RTRIEV function
Field	Description	Set by
CS-ReturnCode	Function request return code. Valid values are: 0 RETRIEVE was successful. 4 or greater RETRIEVE failed. Examine the return message for further diagnostic information.	API
CS-Message	This field contains a text string suitable for display. An informational message might be returned when CS-ReturnCode = 0. Important: CS-Message should be set to spaces before each structured API request.	API