Adding an Object Set for Spool File Data

The stored procedure is in the DB2® schema to add an object set for spool file data.

Note: only SNA Character String (SCS) data is supported. Spool files that contain other types of data cannot be indexed and will result in a document level error when encountered. The error will be logged in the job log, and indexing will continue with the next spool file. The GET_OBJECTS_NOT_INDEXED procedure can be used to determine which spool files were not included in the indexing process.

ADD_SPLF_OBJECT_SET

Authorization

This stored procedure is created with public authority *EXCLUDE and is owned by the creator of the text search collection. will be shipped with *EXECUTE authority granted to public.

The procedure will adopt the authority of the text search collection owner's profile. Authority can be granted to other users to allow them to execute the procedure.

Syntax

Add a Spool File Object Set:

The following simplified versions of the add spool file object set procedure may be used for convenience.

Select spool files by output queue only:

Select spool files by output queue, and user name only:

The schema qualifier is the name of the text search collection.

Parameters

output_queue_lib

A system name for the output queue library.

A NULL value or empty string indicates that output queues in all libraries will be included in the index.

The data type for this parameter is VARCHAR(10)

[See system name conventions]

[See additional restrictions]

output_queue_name

A system name for the output queue name.

A NULL value or empty string indicates that any output queue will be included in the index.

The data type for this parameter is VARCHAR(10)

[See system name conventions]

[See additional restrictions]

user_name

A system name for the user that owns the spool file.

A NULL value or empty string indicates that no filtering on the user name will be performed.

The data type for this parameter is VARCHAR(10)

[See system name conventions]

[See additional restrictions]

qual_job_name

Name of the job that created the spool file.

A NULL value or empty string indicates that no filtering on the job name will occur.

The data type for this parameter is VARCHAR(10)

[See system name conventions]

qual_job_user

System name for the user profile name of the job associated with the spool file.

A NULL value or empty string will indicate that no filtering on the job user will occur.

The data type for this parameter is VARCHAR(10)

A non-null, non-empty value for this parameter is required if QUALIFIED_JOB_NAME is specified.

If QUALIFIED_JOB_NAME is empty string or NULL, this parameter must also be NULL or empty string.

[See system name conventions]

[See additional restrictions]

qual_job_number

A six character string representing the job number. (Must be digits 0-9)

A NULL value or empty string will indicate that no filtering on the job number will occur.

The data type for this parameter is VARCHAR(6)

A non-null, non-empty value for this parameter is required if QUALIFIED_JOB_NAME is specified.

If QUALIFIED_JOB_NAME is empty string or NULL, this parameter must also be NULL or empty string.

[See system name conventions]

[See additional restrictions]

user_data

A ten character string that the user associates with a spool file.

This string is not converted to uppercase, and must exactly match the user data associated with a spool file in order to be considered a match.

Note: A value of 'abc' is different than 'ABC'

A NULL value, or empty string will indicate that no filtering on the user data will occur.

The data type for this parameter is VARCHAR(10)

begin_timestamp

Timestamp value indicating the earliest creation time that will be included in the collection. Spool files created earlier than this timestamp will not be indexed.

A value of NULL can be provided to indicate that any spool file created before the ending creation timestamp value should be indexed. If END_TIMESTAMP is also NULL, then no filtering on the creation timestamp will occur.

The data type for this parameter is TIMESTAMP

end_timestamp

Timestamp value indicating the latest creation time that will be included in the collection. Spool files created after this timestamp will not be indexed.

A value of NULL can be provided to indicate that any spool file created after the BEGIN_TIMESTAMP will be indexed. If BEGIN_TIMESTAMP is also NULL, then no filtering on the creation timestamp will occur.

The data type for this parameter is TIMESTAMP

output_set_id

Output Integer value that returns the set id for the object set that was added.

This value can be used to remove the object set at a later time.

This parameter is optional.

The data type for this parameter is INTEGER

System Naming Conventions

Parameters that require system names as input must be valid system names or an error will occur. This parameters will be processed the same way the command analyzer processes names for CL commands. See Object naming rules for more information on system names

call nick12345.add_splf_object_set('ntl', 'justtext', 'ntl', '', '', '', '', NULL, NULL);

The filter information passed to the procedure will be an output queue NTL/JUSTTEXT for user NTL (converted to uppercase)

Unlike SQL names, for a system name the delimiters will remain on the name, but only if necessary. call nick12345.add_splf_object_set('"ntl"', '"justtext"', '"NTL"', '', '', '', '', NULL, NULL);

The filter information passed to the api will be output queue "ntl"/"justtext" for user NTL (no quotes around user NTL)

Note: The stored procedure has a ten character limit on the interface and does not support unnecessary double quotes that cause this limit to be exceeded.

Invalid system names will cause an error.

Additional Restrictions

Generic names are not supported. In other words it is not possible to index all output queues that start with MYOUT by adding an object set for MYOUT*
The output queue library name and output queue name must either be both null (or empty string)...or both have valid system names. It is not possible filter on all output queues in library xyz, or to filter on all output queues named 'abc' in any library.
If a specific output queue name and library are specified, that output queue must exist at the time the object set is added. There is no logic to prevent the deletion of the output queue at some later time, but the object set will effectively become 'empty'.
If both USER_NAME and QUALIFIED_JOB_USER are non-null, non-empty values, then they must be equal. A spool file owner will always match the qualified job user, and therefore these values can never be different when both are used as a filter.

Authorities to Indexed Objects

When adding a spool file object set, consider the authority requirements needed to retrieve the text from the spool files carefully. These authorities will be a factor when the UPDATE stored procedure is invoked. See the update stored procedure documentation for information on the authority requirements to indexed objects.

Examples

Add an object set to collection nick789 for all spool files in output queue NTL/MYOUTQ.

> call nick789.add_splf_object_set('NTL', 'MYOUTQ');

Add an object set to collection nick123 to index all spool files owned by user NTL.

> call nick123.add_splf_object_set('', '', 'NTL');

Add an object set to collection default_search_col to index all spool files created in 2010

> call default_search_col.add_splf_object_set('', '', '', '', '', '', '', '2010-01-01T00:00:00', '2011-01-01T00:00:00');

Add an object set to collection default_search_col to index all spool files created in 2010 with user data 'MYAPP':

> call default_search_col.add_splf_object_set('', '', '', '', '', '', 'MYAPP', '2010-01-01T00:00:00', '2011-01-01T00:00:00');

To add spool file object set to a collection from IBM® Navigator for i, follow these steps.

From IBM Navigator for i, expand IBM i Management > System > All Tasks.
On the right panel, select System > OmniFind > Collection List.
Right click the collection and select Properties. On the Object tab, press Add Output Queues or Add Spooled Files button.