Parameters

-a

Start of change For the GET function, when retrieving AFP or XML documents, specify this parameter to include resources with the documents that are retrieved. If documents from the same application have different resource groups, then the ARSDOC program creates separate output files for each resource group. End of change

For the ADD function, you must specify the name of the IBM® Content Manager OnDemand application. The application must belong to the application group named with the -g (or -G) parameter.

Start of change Note that resource groups for XML documents are always written to a separate file, and are never added to the same file that contains document data even when the -c option is specified. End of change

-A value

Use this parameter to retrieve annotations. The following are the basic values of this parameter:

0: Include public text annotations
1: Include private annotations
2: Include annotations that cannot be copied to another server
4: Include graphic annotations

You can also add up two or more of the basic parameter values to create new values. For example:

3: Retrieve all public and private text annotations
5: Retrieve public and private annotations (text and graphic) that can be copied to another server
6: Retrieve all public annotations (text and graphic)
7: Retrieve all text and graphic annotations

Table 1. Possible values for the ARSDOC GET function -A parameter
Flag value	Public	Text	Can be copied	Private	Cannot be copied	Graphic
-A 0	X	X	X
-A 1	X	X	X	X
-A 2	X	X	X		X
-A 3	X	X	X	X	X
-A 4	X	X	X			X
-A 5	X	X	X	X		X
-A 6	X	X	X		X	X
-A 7	X	X	X	X	X	X

See Examples for examples of using the -A parameter with the ARSDOC GET function.

-B orderbystring

For the QUERY and PRINT functions, used to specify which database field is used to sort the document list. The -B option cannot be specified if a load ID is specified.

-c

For the GET function, use to concatenate all of the documents that match the query into one output file. Name the output file with the -o parameter. However, even if you do specify the -c parameter, the ARSDOC program creates separate output files when any of the following conditions occur:

If more than one application group is referenced by the folder. The ARSDOC program creates one output file for each application group that contains items that match the query.
If more than one application is contained in an application group. The ARSDOC program creates one output file for each application that contains items that match the query.
If documents from the same application have different resource groups, the ARSDOC program creates separate output files for each resource group.

For example, if a folder references two application groups, then the following specification:

-o student -c

Can result in file names such as: student.516 or student.517

Where 516 and 517 are application group identifiers. One file is created for each application group. Each file contains all of the items that match the query for that particular application group.

If you have difficulty viewing documents that are retrieved in the same file, retrieve the documents as individual documents.

-d directory

The name of the directory where the ARSDOC program writes the output files. The directory must exist before the ARSDOC program attempts to save the output files.

For UNIX servers, directory names are case sensitive; for Windows servers, directory names are not case sensitive.

-D

For the QUERY function, appends the document handle information to the end of each line. The document handle information consists of the following ten values, in the order listed:

Document name
Offset
Length
Compressed object offset
Compressed object length
Annotation type
Compression type
Resource ID
Primary node ID
Secondary node ID

The values are separated by a delimiter. The default delimiter is the comma character. You can specify a different delimiter with the -e parameter.

-e delimiter

For the QUERY function, specifies a one character delimiter to use as a separator between values. By default, Content Manager OnDemand separates values in the output with a comma.

-f folder

The name of the Content Manager OnDemand folder. The folder name must be specified exactly as it appears in Content Manager OnDemand. The case of the folder name is significant. For example, to query the System Log folder, you must enter:

-f "System Log"

If you are using a parameter file, then you must specify the -f parameter in the parameter file. If you are not using a parameter file and you do not specify the -f parameter, then the ARSDOC program prompts you for the folder name when you run the program.

For the GET and QUERY functions, you can omit the -f parameter and specify the -G parameter to search a specific application group.

For the UPDATE function, if the folder that is specified with the -f parameter contains only one application group, then you can omit the -g or -G parameter (you do not have to specify the name of the application group).

When you specify the -X parameter, you cannot specify the -f parameter.

Note: The following information applies only when an application group name is not provided.

A folder can be used to search one or more application groups. Because the ARSDOC program generates a single SQL query to search all of the application groups, the properties of the database fields must be the same for each application group. The properties include the field name, type, and length. For example, suppose that you define the following application groups and fields:

Application Group	Field Names
Student Bills	name, account, billDate
Student Grades	name, account, gradeDate
Student Transcripts	name, account, transcriptDate

You cannot query the application groups using the ARSDOC program because the name of the date field is not the same for each application group. However, if you were to define the application groups and fields as follows:

Application Group	Field Names
Student Bills	name, account, studentDate
Student Grades	name, account, studentDate
Student Transcripts	name, account, studentDate

Then you could query the application groups using the ARSDOC program because the names of the database fields are the same for each application group.

-F parmFile

Specifies the name of the file that contains the actions to run and other parameters, values, and options. You typically specify this option when you want to perform more than one action.

When you specify a parameter file, delimit the options and values with left [ and right ] brackets. The left and right brackets identify each parameter in the file, are required in the parameter file, and the parameter values cannot contain left or right brackets. In the following example, the parameter file for the ARSDOC query function is parmfile.txt:

arsdoc query -u oduser -p odpasswd -h odserver -v -F parmfile.txt

The following lines are examples of parameter values in the parmfile.txt parameter file:

[-f "Credit Card Statements"] [-i "where account = '000-000-000'"]
[-f "Credit Card Statements"] [-i "where account = '000-000-001'"]

If you want to use the left or right bracket as part of a parameter value, add a line to the beginning of the file that redefines the left and right delimiters with the keyword DELIMS. The keyword DELIMS is case-sensitive, must be on the first line of the file and it must start at the beginning of the line. For example, if you want to indicate that the left and right curly braces are the delimiters, add the line DELIMS={}. You can specify any two characters that are different, are not a space, and are not in any of the parameter values. The following example shows left and right curly braces defined as delimiters:

DELIMS={}
{-f "Credit Card Statements"} {-i "where account = '000-000-000' and name = 'Republic Bank [North]'"}
{-f "Credit Card Statements"} {-i "where account = '000-000-000' and name = 'Republic Bank [South]'"}

An action (one or more input lines) can contain a maximum of 32767 characters (bytes).

You can use the \ (backslash) character to continue the parameters of an action to two or more lines.

A parameter file can contain blank lines and comment lines. A comment line contains the # character in the first column.

-g

For the GET function, use to generate Generic indexer data for the items that match the query.

See the IBM Content Manager OnDemand Indexing Reference for details about the Generic indexer.

When you specify the -g parameter, you must specify the -c, -N, and -o parameters. However, you cannot specify database field names with the -o parameter.

The ARSDOC program uses the following convention to name the output files that are generated with the -g parameter:

-o.res_id.appl_group.appl.type

Where:

-o is the value specified with the -o parameter
res_id is the resource group identifier.
appl_group is the name of the application group
appl is the name of the application
type is the file type:
- out identifies a document file
- ind identifies a generic index file
- res identifies a resource file

In general, the number of files generated is dependent on the number of application groups in a folder, the number of applications in an application group, and the number of versions of resource groups in an application.

For the ADD and UPDATE functions, specifies the name of the Content Manager OnDemand application group. The application group that you specify will be searched from the folder that is named with the -f parameter. For the UPDATE function, if the folder that is specified with the -f parameter contains only one application group, then you can omit the -g parameter (you do not have to specify the name of the application group).

-G applGroup

Use to specify the name of the application group.

For UPDATE: If the folder that is specified with the -f parameter contains only one application group, then you can omit the -G parameter (you do not have to specify the name of the application group).

For ADD: When the database query is run to retrieve the document that contains the data that is to be used in the add function, the search is limited to the specified application group, even if the folder named with the -f parameter can be used to search more than one application group. This ensures that only documents in the specified application group can be used for the add function. You can specify the name of the application group with the -g parameter or the -G parameter.

For DELETE: The -G parameter is an optional parameter. If specified, then the database query that is run to determine the document(s) to delete is limited to the specified application group. The addition of the -G parameter allows you to delete documents from a specific application group in folders that can search more than one application group. If you do not specify the -G parameter, then the query runs against all of the application groups that can be searched from the folder.

For GET: Specifies the application group to query and retrieve documents from. The -G parameter lets you retrieve documents from a specific application group from a folder that can search more than one application group. If you do not specify the -G parameter, then the query runs against all of the application groups that can be searched from the folder. You can omit the -f parameter and specify the -G parameter to search a specific application group. The -G parameter is required if you specify the -X parameter.

For PRINT: The -G parameter is an optional parameter. If specified, then the database query that is run to determine the document(s) to print is limited to the specified application group. The addition of the -G parameter allows you to print documents from a specific application group in folders that can search more than one application group. If you do not specify the -G parameter, then the query runs against all of the application groups that can be searched from the folder.

For QUERY: Specifies the application group to search. The -G parameter lets you search a specific application group from folders that can search more than one application group. If you do not specify the -G parameter, then the query runs against all of the application groups that can be searched from the folder. You can omit the -f parameter and specify the -G parameter to search a specific application group. The -G parameter is required if you specify the -X parameter.

For UPDATE: When the database query is run to determine the document(s) to update, the search is limited to the specified application group, even if the folder named with the -f parameter can search more than one application group. This guarantees that only documents in the specified application group can be updated. You can specify the name of the application group with the -g parameter or the -G parameter.

You can use the -G parameter with the -i parameter to query folders that can search more than one application group. For example, a folder contains three application groups; you want to query only one of the application groups. Use the -G parameter to specify the name of the application group that you want to query. Use the -i parameter to specify the application group's database field names. You can also use the -G and -i parameters when the application groups have different database field names. The following example shows how to search a folder and three application groups that have different database field names:

arsdoc get -f "Student Information" -G loans
    -i "WHERE number LIKE '123456' AND loanDate = 10593"
arsdoc get -f "Student Information" -G grades
    -i "WHERE number LIKE '123456' AND gradeDate = 10593"
arsdoc get -f "Student Information" -G transcripts
    -i "WHERE number LIKE '123456' AND transDate = 10593"

You can use the -G parameter with the -q parameter to query folders that can search more than one application group. When you specify the -G parameter and you specify a public named query with the -q parameter, the ARSDOC program queries the application group named with the -G parameter instead of the application group specified in the named query. (If you do not specify the -G parameter, then the query runs against the application group specified in the named query. If the named query does not identify an application group, then the query runs against all of the application groups that can be searched from the folder.)

-h instance

The name of the Content Manager OnDemand instance to process.

The ARSDOC program will attempt to locate the specified instance name in the ARS.INI file (UNIX servers; the registry on Windows servers) to obtain the TCP/IP address, host name or host name alias of the workstation or node on which the instance is running. If the ARSDOC program cannot locate the instance name in the ARS.INI file, the specified value is treated as a host name.

This is a required parameter.

Important: If you are running multiple instances of Content Manager OnDemand on the same workstation, always specify the -h parameter to identify the name of the instance that you want to process. Verify that the system is configured with the correct information for all instances of Content Manager OnDemand.

See IBM Content Manager OnDemand for Multiplatforms: Installation and Configuration Guide for information about configuring instances.

-H

For the QUERY function, specify this parameter to generate a header record in the output. The default header record contains the application group field names. This parameter also generates a line that contains the names of the database fields. By default, the field names are delimited with the comma character. You can specify a delimiter of your choice with the -e parameter.

You can use the -H parameter to generate output that contains only the application group database field names. To do so, specify the -H parameter without specifying the -i or -q parameters. (You also must not specify the -L, -n or -N parameters.)

The ARSDOC program writes the database field names to the specified output file or to stdout (UNIX servers) or the console (Windows servers), in the format used for the header record.

-i sqlQuery

A valid SQL query, that includes the names of one or more application group database fields, index values, and operators. Content Manager OnDemand does not validate the string that you specify. See the SQL reference for your database manager product for an overview of SQL concepts and details about how to construct a query.

Restriction: If you specify the -q or the -X parameters, then you cannot specify the -i parameter.

For the DELETE or UPDATE functions, if more than one document meets the search criteria, then multiple documents will be deleted or updated. For an update, all of the documents will be updated with the same values.

To construct a query with a database field of type Date (old style), Date/Time (old style), Date/Time (TZ) (old style), or Time (old style), you must use the Content Manager OnDemand internal format of the date. That is, the number of days since January 1, 1970. You can use the ARSDATE program to list the internal format for a given date string. For example, the following shows how to use the ARSDATE program on an AIX® server to obtain the internal date for July 21, 1995:

/opt/IBM/ondemand/V9.5/bin/arsdate -a 7/21/95

The ARSDATE program displays:

7/21/95 -> 9333

You would then enter 9333 as the index value for the date field.

-I

Important: When you use this parameter, you must specify the f or p variable. For example:

arsdoc query .. .-I f

For the QUERY function, this parameter appends the Load ID to each line. The Load ID is separated from the database field values by a delimiter. The default delimiter is the comma character. You can specify a different delimiter with the -e parameter. You cannot specify the -H, -n, or -N parameters when you specify the -I parameter.

To use the -I parameter, the user running the query must have permission to access the System Log application group and folder.

If the Load ID is not found in the system log, then the string Load ID could not be found is appended to the end of the output record.

The Load ID for a document is determined by searching the system log. Searching the system log can be very time consuming, depending on the number of records stored in the system log. The system log is searched for each document that matches the query.

-l holdname

For the GET, QUERY, PRINT, HOLD_ADD, and HOLD_RELEASE functions, this parameter specifies the hold name. Do not specify this parameter when you specify the -X parameter. Do not specify this parameter if only database names are specified. Specifying the hold name limits the list of returned hits to only those hits that have been added to the specified hold. For example, an SQL query or a Named Query produces 10 hits. If 2 of the 10 hits have been added to a hold and the hold name is provided, the result contains only the two hits that are included in the hold.

-L max#

For the GET and PRINT functions, determines the maximum number of items retrieved from Content Manager OnDemand, regardless of the number of items that match the query.

For the QUERY function, determines the number of items included in the hit list, regardless of the number of items that match the query.

-n

For the GET function, use to retrieve items one at a time from the server. By default, the ARSDOC GET function uses a bulk retrieval method for high-speed retrieval of items from the server.

For the QUERY function, use to number the items in the output file. If you specify this option, the ARSDOC program sequentially numbers each line in the output file, beginning with 1 (one).

For the ADD and UPDATE functions, use to specify the application group database field names and their values using the form -n dbfield=value.

Specify a null (blank) field value by using single quotes within double quotes. For example: -n middle="''"
Specify a string field value that contains a null (blank) or other special character by enclosing the field value in single quotes within double quotes. For example: -n name="'Sally Smith'"

You can specify one or more field names and their values (by specifying the -n parameter one time for each database field name and its value). When adding a document, you must specify all of the application group fields unless you specify the -O parameter. When updating a document, you can specify one or more fields and their values. For a date field, you must specify the value using the Display Format from the Field Information page under folders.

-N "(dbfield1)(dbfield2)(dbfieldn)"

For the QUERY function, specify the order and names of the database fields to include in the output. For the GET function, when querying a folder that searches more than one application group or a folder that searches an application group that contains more than one application, specify this parameter to add the resource identifier, application group name, and application name to the output file name. When you specify the -N parameter, you must specify the -c parameter. If you specify the -g parameter to generate generic index data, you must specify the -N parameter.

If the folder searches more than one application group or an application group contains more than one application and you do not specify the -N parameter, then the ARSDOC program adds the application group or application identifier to the output file name. For example, the following specification:

-o student -c

Can result in output file names such as: student.516 or student.517

Where 516 and 517 are application group identifiers. However, when you specify the -N parameter, the ARSDOC program uses the resource identifier, application group name, and application name to name the output file. For example, the following specification:

-o student -c -N

Can result in output file names such as: student.1.BILLS.1995 or student.1.BILLS.1996

Where 1 is the resource identifier, BILLS is the application group name, and 1995 and 1996 are application names.

The number of index files created is dependent on the number of application groups in a folder, the number of applications in an application group, and the number of resource groups in an application.

For the QUERY function, determines the application group fields that the ARSDOC program writes to the output file and the field names that appear in the header record. By default, the ARSDOC program writes all fields to the output file. You can specify one or more application group field names using the form -N(dbfield)...(dbfield). Each field name that you specify must be delimited with parenthesis. When you run a query from the command line, you must delimit the entire string in double quote characters. For example, -N"(dbfield)...(dbfield)".

-o name

For the GET function, use to write documents to one or more files and identify a user-defined string used to generate unique file names. For example, the following specification:

-o student -c

Can result in the following output file name: student

You can concatenate one or more of the database field names that you specify with the -i parameter to generate a unique file name. For example, the following specification:

-o "(sdate)(student)"
-i "WHERE sdate='971025' AND student='001200340056'"

Can result in the file name: 971025.001200340056

When you use database field names to generate a unique file name:

Content Manager OnDemand verifies that the field names that you specify are valid for the application groups that can be searched by the folder specified with the -f parameter.
If the field name that you specify is a date field, the output format of the date is determined by the Format on the Load Information page under applications.
The field names must be delimited with parenthesis.
You can specify the fields in any order. The order that you specify determines the file name that the ARSDOC program generates.
You cannot use a field name to represent a directory name. For example, the following is not valid:
```
-o "(field_1)/(field_2)
```
You cannot specify the -c parameter to concatenate items in one output file. Each item that matches the query is stored in a separate output file.

If more than one item matches a query and you do not generate a unique file name using database field names, concatenate items in a single file with the -c parameter, or specify the -g parameter, then the ARSDOC program generates a unique file name for each item that matches the query by adding a .n extension to the file name. Where n is the number of the item that matched the query. For example, if you specify:

-o statements

And two items match the query, the ARSDOC program creates the following files: statements.1 and statements.2

You must specify the -o parameter when you specify the -c parameter.

For the QUERY function, determines the file name of the output file in which the ARSDOC program writes the list of items that match the query.

For the ADD function, determines the name of the input file that contains the document to be added. The value that you specify is not checked for valid characters. You can specify a full path name, including the back slash or forward slash characters that are part of a directory path. When adding a document, you can provide the input data by specifying the name of the input file that contains the data with the -o parameter, an SQL query with the -i parameter, or a public named query with the -q parameter. Only one document may be added at a time.

-O

For the ADD function, you must specify this parameter if you intend to omit one or more database fields. However, you can never omit the following fields:

Date
Date (old style)
Date/Time
Date/Time (old style)
Date/Time (TZ)
Date/Time (TZ) (old style)

When you specify the -O parameter, the ARSDOC program stores a default value in any other database field that you omit. The default value for string fields is an empty (null) string. The default value for numeric fields is 0 (zero). Numeric fields include integer and decimal fields.

The -O option is not required in the case where an index row is being added for an existing document. For any index values that are not provided, the values from the existing document are used.

-p password

Specify one of the following options for password:

The name of the stash (encrypted password) file that contains the password for the user ID specified with the -u parameter.
The password of the Content Manager OnDemand user that you named with the -u parameter. If there is no password assigned to the user that you specify, use quotation marks to show a null password. That is, specify -p "". If you do not specify the -p parameter while you specify the -u parameter, then the ARSDOC program retrieves the password for the user ID from the stash file specified in ARS.INI file for that instance. If there is no password assigned to the user that you specify, press the Enter key when prompted.

-P

Indicates PDF files that are retrieved and should be stored in individual files even if concatenation has been requested.

-P printer

For the PRINT function, identifies the Content Manager OnDemand server printer to which you want to send the documents that match the query.

-q namedQuery

The name of a public named query for the folder named with the -f parameter. A named query is a set of search criteria previously saved on the library server that can be recalled by name to search a folder. A named query is typically defined to search a folder for a specific document or set of documents.

Restriction: If you specify the -i or the -X parameters, then you cannot specify the -q parameter.

-Q SQLqueryfile

Use this parameter to specify a file name that contains one or more query strings. Specify only one of the parameters, -i, -q, or -Q.

-s seconds

For the GET function, determines the number of seconds that the ARSDOC program waits between query requests when you specify more than one query with the -F parameter. If you do not specify this option, then the ARSDOC program does not wait between query requests. That is, the default is 0 (zero) seconds.

-S startdate,enddate,format

Provides a date range that the ARSDOC program uses to limit a search to specific tables. When you specify this parameter, the ARSDOC program searches only tables that contain a segment within the specified date range.

You can optionally specify a date format. See ARSDATE for a list of the standard date formats. An example of a date range with a date format is:

-S "01011990,12311990,%m%d%Y"

If you do not specify a date format, then the date values must be specified by using the Display Format that is set on the Field Information page in the folder. An example of a date range without a date format is:

-S "01011990,12311990"

Important:

For most queries, you should always specify the -S parameter and specify a date range. Doing so limits the range of a query and can significantly improve the performance of a query.
For the ADD function, if you specify the -o parameter, you cannot specify the -S parameter.
For the GET and QUERY functions, if you specify the -X parameter, you cannot specify the -S parameter.
For all functions, if you specify the -q parameter, you cannot specify the -S parameter.

-t search_str

Search for the string search_str using the Content Manager OnDemand search.

-T search_str

Search for the string search_str using the full text index search.

-u userid

The Content Manager OnDemand user that is permitted to perform the specified function. The ARSDOC program verifies the following permissions:

the user ID that you specify is a valid Content Manager OnDemand user for the library server that you name with the -h parameter
the user ID is permitted to open the folder that you name with the -f parameter
the user ID has permission in application groups to perform the specified function

If you omit the -u parameter, then the ARSDOC program prompts you to enter the user ID when you run the program.

Start of change If you do not specify the -p parameter while you specify the -u parameter, the ARSDOC program retrieves the password for the user ID from the stash file specified in ARS.INI file for that instance. End of change

-U user_alias

Identifies the users when multiple users share a common user ID. The maximum length for user_alias is 128.

-v

Enables verbose mode, which displays all messages (informational and error). By default, the ARSDOC program displays error messages.

-x loadId

For the GET function, use to limit the documents that can be retrieved to the set of documents that were loaded into the system under the specified loadId.

For the QUERY function, use to limit the query to the set of documents that were loaded into the system under the specified loadId.

When you specify the -x parameter, use the -f and -G parameters as follows:

Specify the -f parameter to search all application groups. You can specify the search using the -i parameter or the -G parameter.
Specify the -g parameter to search a specific application group. You must specify the search using the -i parameter.
Specify both the -f parameter and the -G parameter. The ARSDOC program verifies that the application group can be searched from the folder.

When you specify the -x parameter, you cannot specify the -X parameter.

-X loadId

For the GET function, retrieve documents by using the index file that was generated for the specified loadId.

Important: Content Manager OnDemand does not retrieve any documents with index values that you updated.

For the QUERY function, build a hit list from the index file that was generated for the specified loadId.

For the PRINT function, the -i SQL parameter can be specified when the -X flag is used. If it is specified, it is used only if the retrieve fails using the loadID. If the -X flag is used, the application group name must be provided using the -G flag.

For the HOLD_ADD function, add documents to a hold by using the index file that was generated for the specified loadId.

For the HOLD_RELEASE function, remove documents from a hold by using the index file that was generated for the specified loadId.

For the CFSOD-FED function, send documents to CFS-OD and make them available to IBM FileNet® P8 features by using the index file that was generated for the specified loadId.

When you specify the -X parameter, you must specify the -G parameter and name the application group.

When you specify the -X parameter, you cannot specify the -x parameter, or the -i, -q, -S, and -f parameters.

-1 trace_file

Specify a fully qualified trace file name as directed by IBM Software Support. End of change

-2 level

Specify a numeric value as directed by IBM Software Support. End of change