FOLDER OPEN API

A FOLDER OPEN request passes a complete folder name to the API in order to perform an open of one specific folder on the Content Manager OnDemand server. This request can only be performed after a successful LOGON. A successful FOLDER OPEN request will return a table of criteria field names (up to a maximum of 128) and associated field information for the specified folder name. The returned criteria field names and logical operators are used to specify search arguments for subsequent HIT LIST and RETRIEVE function requests.

The fields listed in Table 1 must be specified by the customer application in the CS-CommonStructure before issuing the FOLDER OPEN function request

Table 1. CS-CommonStructure fields for the FOLDER OPEN function
Field Description Required or optional?
CS-Request Function request value of FOLDER OPEN. Required
CS-FolderName Fully qualified folder name. This value is matched against the value found when you select Folders > General > Folder Namein the OnDemand Administrator client.
Note: This folder name must match a name returned in the FL-FolderListStructure. Users who run in Content Manager OnDemand Version 2 compatibility mode must make certain the value specified for CS-FolderListMax is large enough to allow the folder name requested for FOLDER OPEN to be returned FL-FolderListStructure.
 Required
CS-NumSecs-to-Wait A non-zero number might be entered to specify the wait time for a FOLDER OPEN request to complete. Default is 120 seconds.
Note: If a non-zero value is specified, it remains in effect for all subsequent API requests until a new value is specified.
 Optional

Table 2 and Table 3 list the fields that are returned from the Content Manager OnDemand server following the FOLDER OPEN request. The fields are provided in the CS-CommonStructure and FC-FolderCriteriaStructure (pointed to by CS-pFolderCriteria).

Values returned in the storage area addressed by pointer CS-pFolderCriteria include a table whose entries consist of folder criteria names and associated field values. A count field is supplied that indicates the number of entries in the table.

Note: Following the successful FOLDER OPEN, the customer application program must execute the following statement to gain access to the fields: Set address of FC-FolderCriteriaStructure to CS-pFolderCriteria
Table 2. CS-CommonStructure fields returned by the FOLDER OPEN function
Field Description Field set by
CS-pFolderCriteria Pointer to the Content Manager OnDemand folder criteria structure. The folder criteria returned at this address is defined by the fields under group item name FC-FolderCriteriaStructure. API
CS-ReturnCode Function Request Return Code.
Valid values are:
0
FOLDER OPEN was successful
4 or greater
FOLDER OPEN was unsuccessful. Examine the return message for further diagnostic information
 API
CS-Message This field will contain a text string suitable for display. An informational message may be returned when CS-ReturnCode is equal to zero.
Note: CS-Message should be set to "spaces" before each Structured APIs request.
 API
Table 3. FC-FolderCriteriaStructure fields returned by the FOLDER OPEN function
Field Description Field set by
FC-Count The number of folder criteria entries in the table.

The following fields represent a table of folder criteria fields (1 to 128) for the requested folder.

 Content Manager OnDemand server
FC-CriteriaName The folder criteria name. The name correlates to the value you find when you select Folders > Field Information > Field Namein the OnDemand Administrator client. Content Manager OnDemand server
FC-PermOPs The valid search operators for the folder criteria. The appropriate bit will be on for each query operator allowed.
X'0001'
Equal
X'0002'
Not Equal
X'0004'
Less Than
X'0008'
Less Than or Equal
X'0010'
Greater Than
X'0020'
Greater Than or Equal
X'0040'
In (not supported)
X'0080'
Not In (not supported)
X'0100'
Like
X'0200'
Not Like
X'0400'
Between
X'0800'
Not Between

The values correlate to the values you find in the Operators box when you select Folders > Field Informationin the OnDemand Administrator client.

 Content Manager OnDemand server
FC-DefOP The default search operator for the criteria. The valid values are the same as those displayed above for field FC-PermOPS. Only one bit is set in this field. The value correlates to what you find in the Default section of the Operator box when you select Folders > Field Informationin the OnDemand Administrator client. Content Manager OnDemand server
FC-CritMaxEntry The maximum length of the search criteria value. Content Manager OnDemand server
FC-DefValueCount The number of default search argument values for this criteria. A criteria that provides default search values is assumed by the APIs to be a required search criteria.
0
No default values
1
Single default value
2
Two default values (supported only with the Between and Not Between operators)

This value correlates to what you find when you select Folders > Field Information > Default Value 1 in the OnDemand Administrator client.

 Content Manager OnDemand server
FC-DefValue1 The default value of the first search (or only) search criteria value. This value correlates to what you find when you select Folders > Field Information > Default Value 1 in the OnDemand Administrator client. Content Manager OnDemand server
FC-DefValue2 The default value of the second search criteria value. This value correlates to what you find when you select Folders > Field Information > Default Value 2 in the OnDemand Administrator client. Content Manager OnDemand server
FC-SortDefault The default sort value. The valid values are:
A
Ascending
D
Descending

This value correlates to what you find in the Ascending check box when you select Folders > Field Information in the OnDemand Administrator client.

 Content Manager OnDemand server