11

Chapter 11. Exits

In IBM Content Manager OnDemand (Content Manager OnDemand), you can use exit points
to customize and enhance the standard functionality within the product. This chapter
introduces various exit points within the Content Manager OnDemand product. By using
working sample code, we present examples of the types of operations and enhanced
functions that are possible.

In this chapter, we cover the following topics:

 Introduction to user exits
 ACIF exits
 OS/390 indexer exits
 System administration
 Customized functions (Multiplatforms and z/OS only)

© Copyright IBM Corp. 2003, 2015. All rights reserved. 241

11.1 Introduction to user exits
A user exit is a point during processing where you can run a user-written program and return
the control of processing after your user-written program ends. Several kinds of exits exist. In
this chapter, we describe the exits based on the following categories:
 AFP Conversion and Indexing Facility (ACIF) indexing
The ACIF indexer contains user exit points for increased flexibility. Four exit points are
available during ACIF processing where user programs can be configured:
– Input record exit
– Index record exit
– Output record exit
– Resource exit
 OS/390 indexer exits
The OS/390 indexer supports three exits to assist with indexing and loading documents
into Content Manager OnDemand:
– Anystore exit
– Input exit
– Index exit
 System administration:
– System log exit
– Print exit
 Customized functions:
– User exit
– Load exit
– Client Retrieval Preview exit
– Report specifications archive definition exit
– Table space create exit
– ARSYSPIN and sample APKACIF exit on z/OS

Content Manager OnDemand provides data at each exit that can serve as input to the
user-written programs. By using these exits, you can perform functions, such as sending
emails based on events in the system, updating index values through a print request, and
cleaning up data as it is loaded into Content Manager OnDemand. Unlimited possibilities are
available with the Content Manager OnDemand exits. We provide samples to act as a guide
for creating customized user exit programs.

Important: Always recompile all of the customized user exits after you upgrade the
Content Manager OnDemand software because the header files might change with
different versions.

PDF Indexer: The PDF Indexer does not support any user exits.

11.2 ACIF exits

The ACIF user exit is a point during the ACIF processing where control is transferred from
ACIF to a user-written program. After the user-written program finishes, the control is
returned to ACIF. User programs can be configured at four points during ACIF processing:
input, indexing, output, and resource.

242 IBM Content Manager OnDemand Guide

 Note: ACIF exits are called for every input, indexing, output, and resource record. ACIF
exits are not limited to being called only one time for each file.

In Multiplatforms, ACIF user exits must be written in C. In z/OS, ACIF user exits can be written
in C, COBOL, or assembler. For more information, see the “Special considerations for
APKACIF exits written in COBOL” section in the IBM Content Manager OnDemand for z/OS,
V9.0, Administration Guide, SC19-3364. ACIF exits do not exist in Content Manager
OnDemand for IBM i.

For detailed documentation about each exit point, see IBM Content Manager OnDemand for
Multiplatforms - Indexing Reference, SC19-3354, and IBM Content Manager OnDemand for
z/OS and OS/390 - Indexing Reference, SC27-1375.

11.2.1 New macro for user exits

Because the default installation directory changed for Content Manager OnDemand V9, the
arsload program supports a new macro to make user exits more portable.

For example, instead of specifying the exit as

INPEXIT=/opt/IBM/ondemand/V9.0/exits/acif/asciinpe, specify the following items in the
indexing parameters:
INPEXIT=$(OD_ACIF_EXIT_DIR)asciinpe

The arsload program substitutes the correct path for the platforms.

This macro works for all four ACIF user exits. The macro is not supported if ACIF is run
outside of the arsload program.

11.2.2 Input record exit

ACIF provides the input record exit so that you can add, delete, or modify records in the input
file before they are processed by ACIF. The primary purpose of this exit is to modify input
records before ACIF accesses the records. The exit program is started by the ACIF inpexit
parameter.

The input exit can be used to insert indexing information. More common uses are to remove
null characters, truncate records, add carriage control, and change code pages. In general,
indexer parameters need to reflect what the input record looks like after the input exit runs.
The only exception is the FILEFORMAT indexer parameter, which needs to correspond to the
input record before it is passed to the input exit. For example, if the file contains ASCII data
and uses the ASCII stream delimiter x'0A', specify (NEWLINE=x'0A'), not (NEWLINE=x'25'),
even if you use the apka2e exit to convert ASCII to EBCDIC. Otherwise, ACIF does not pass
the correct record to the apka2e input exit.

Content Manager OnDemand provides three input record exits:

 apka2e
 asciinp
 asciinpe

You can either use these input record exits as samples to build from, or you can compile them
and run them as is. These programs are documented in IBM Content Manager OnDemand
for Multiplatforms - Indexing Reference, SC18-9235, and are described briefly in the following
sections.

Chapter 11. Exits 243

 The apka2e exit
The apka2e exit translates data that is encoded in ASCII (code set IBM-850) into EBCDIC
(code set IBM-037). If you are converting line data to AFP, consider converting the data to
EBCDIC. A much wider selection of EBCDIC coded fonts is available than ASCII fonts. Many
customers find that it is easier to use character sets and code pages that are supplied by IBM
than to create their own character sets and code pages. To use these predefined EBCDIC
coded fonts, the data must be in EBCDIC.

When you use the apka2e exit, you must manually change your indexing parameters:
 Change an ASCII CPGID to an EBCIDIC CPGID; for example, change CPGID=850 to
CPGID=500.
 Change the HEX codes for the triggers and index names from ASCII to EBCDIC. If you do
not, you receive ACIF return code 16, which states that it cannot find trigger1 or any fields.

We used a hex editor to determine the new EBCDIC values and typed them by keyboard edit
into the parameter file. If you do not have a hex editor, you can find conversion tables on the
Internet.

For more information about how to update indexing parameters, see 11.2.6, “Debugging input
user exit programs” on page 247.

The asciinp exit

The asciinp exit program is used when the data does not contain carriage controls. Instead,
it contains “PC style” carriage returns and form feeds X'0D0A' and X'0D0C'. This program is
provided by IBM. The program transforms the ASCII data stream into a format that contains a
carriage control character in byte 0 of every record.

The asciinp exit performs the following actions:

 Inserts a new page command (X'31') at the top of the first page.
 Removes the ASCII carriage return (X'0D').
 Inserts an ASCII new line (X'20') carriage control at byte 0 of each line, except the first
line on a new page.
 Replaces the ASCII form feed (X'0C') with an ASCII new page command (X'31').
 Leaves X'0A' in the file.

Note: Because the asciinp exit inserts carriage control characters in byte 0 of your
document, and leaves X'0A', it changes the position of the triggers and fields. If you use
this exit, you must add 1 to the column offsets for the triggers and fields.

The asciinpe exit

The asciinpe exit combines the previous two exits. It converts the data from ASCII to
EBCDIC and inserts EBCDIC carriage control characters. For full documentation about this
sample program, see the asciinpe.c source code.

11.2.3 Index record exit

Use the index record exit to modify or ignore the records that ACIF writes in the index object
file. The program, which is specified in the ACIF indxexit parameter, receives control before a
record is written to the index object file. The user-written program can instruct ACIF to use the
record, to not use the record, or to edit the record before the record is inserted into the index
object file.

244 IBM Content Manager OnDemand Guide

A good use of this program is for an application that must pull an index from a source other
than the document. The application group can be set up with a default index; then, the user
exit program can grab the appropriate index from this secondary source and replace the
default value that was in the index record. The record is then sent back to ACIF.

Another example is to modify the format of an existing index. Example 11-1 shows a sample
index exit C program to update the date format from mmddyy to mm/dd/yy.

Important: The ACIF index file is in AFP format. It is important to understand the structure
of AFP before you write or modify an index exit.

Example 11-1 Sample ACIF index exit program

#define _c_APKIND
/*********************************************************************/
/* */
/* MODULE NAME: UPDDATE.C */
/* */
/* SYNOPSIS: ACIF Sample Index Exit */
/* */
/* */
/* DESCRIPTION: This module converts the date format */
/* from mmddyy to mm/dd/yy before adding the */
/* record to the index object file */
/* */
/*********************************************************************/
#include "apkexits.h"/* standard acif exit header file */

long
INDXEXIT( INDXEXIT_PARMS *exitstruc )
{
int i;

if ( exitstruc->eof != IDX_EOFLAG )
{
/************************************************/
/* Look for TLE with attribute name "mmddyy" */
/************************************************/
if (
(exitstruc->record[13] == 0x6D) &&
(exitstruc->record[14] == 0x6D) &&
(exitstruc->record[15] == 0x64) &&
(exitstruc->record[16] == 0x64) &&
(exitstruc->record[17] == 0x79) &&
(exitstruc->record[18] == 0x79))
{

/************************************************/
/* TLE length is now 40 (was 38) */
/************************************************/

exitstruc->record[ 2] = 0x28;

/************************************************/
/* Attribute value count is now 12 (was 10) */
/************************************************/

exitstruc->record[19] = 0x0C;

Chapter 11. Exits 245

 /************************************************/
/* Relocate attribute qualifier triplet X'80' */
/************************************************/

for (i=40; i>30; i--)

exitstruc->record[i] = exitstruc->record[i-2];

/************************************************/
/* Change mmddyy to mm/dd/yy */
/************************************************/

exitstruc->record[30] = exitstruc->record[28];
exitstruc->record[29] = exitstruc->record[27];
exitstruc->record[28] = 0x61;
exitstruc->record[27] = exitstruc->record[26];
exitstruc->record[26] = exitstruc->record[25];
exitstruc->record[25] = 0x61;

/**********************************************/
/* record length has increased to 41 (was 39) */
/**********************************************/

exitstruc->recordln = 41;

exitstruc->request = IDX_USE;
}

return( 0 );
}

11.2.4 Output record exit

Use the output record exit to modify or ignore the records that ACIF writes to the output
document file. The program is started by the ACIF outexit parameter, and it gives control to
the user program before a record (which can be a Structured Field or can be line data) is
written to the output (.out) file.

Example 11-2 shows a sample output exit program that deletes records from the output file.
This program checks each Structured Field to determine whether it is an AFP record. If the
record does not begin with Hex 5A, the exit program instructs ACIF not to use this record.

Important: The ACIF output file can be in either Line Data or AFP format. If the ACIF
output file is in AFP format, it is important to understand the structure of AFP before you
write or modify an output exit.

Example 11-2 Sample ACIF output exit program

#define _c_ACCT_OUT
/*********************************************************************/
/* */
/* MODULE NAME: ACCT_OUT.C */
/* */
/* */
/* SYNOPSIS: ACIF Output Exit */

246 IBM Content Manager OnDemand Guide

 /* */
/* DESCRIPTION: This program will delete all non-AFP records (or */
/* records that do not begin with X(5A) from the */
/* output object before giving control back to ACIF */
/* */
/*********************************************************************/
/* Standard acif exit header file */
/************************************************/
*/
#include "apkexits.h"

long
OUTEXIT( OUTEXIT_PARMS *exitstruc )
{

/************************************************************************/
/* Delete all records from the output that do not begin with Hex '5A' */
/************************************************************************/

if(exitstruc->eof != ACIF_EOF)
{
if(exitstruc->record[0] == 0x5A)
exitstruc->request = ACIF_USE;
else
exitstruc->request = ACIF_DELETE;
}
return( 0 );
}

11.2.5 Resource exit

If you want to prevent ACIF from collecting a specific type of resource, such as overlays, you
can use the ACIF restype parameter. However, if you want to prevent ACIF from writing a
specific resource to the resource file, use the resource exit.

The resource exit is best used to control resources at the file name level. For example, you
want to exclude particular fonts from the resource file. You can code this exit program to
contain a table of the fonts that you want to exclude and filter them from the resource file. The
program that is invoked at this exit is defined in the ACIF resexit parameter.

ACIF does not start the exit for the following resource types:
 Page definitions: The pagedef is a required resource for converting line data to AFP and it
is never included in the resource file.
 Form definitions: The formdef is a required resource for processing print files. If you do not
want the formdef to be included in the resource file, specify restype=none or explicitly
exclude the formdef from the restype list.
 Coded fonts: If you specify MCF2REF=CF, ACIF writes coded fonts to the resource file if they
are included in the restype list. The default is MCF2REF=CPCS; therefore, ACIF does not
write coded fonts to the resource file.

11.2.6 Debugging input user exit programs

When you work with an input exit, you must know how the exit changed your data before you
load it. A way to determine how the exit changed the data is to set up ACIF to run in
stand-alone mode (not called from arsload).

Chapter 11. Exits 247

 To set up ACIF to run in stand-alone mode, create an indexing parameter file with no triggers,
fields, or indexes that are defined, and use the value CONVERT=NO. Include your input file,
output file, and the input exit routine in the parameter file. Then, run arsacif from a command
line while you point to this parameter file. Example 11-3 shows our ACIF parameter file,
parmfile. Use the following command to run stand-alone ACIF:
arsacif parmdd=parmfile

This command starts ACIF with the user exit, runs the exit, and writes the output to the file
that is specified by the OUTPUTDD parameter. You can inspect the output file to ensure that the
exit did what you expected. You can also use this output file in the graphical indexer to index
your post-exit file because the exit routine might change the location of your triggers and
fields.

Example 11-3 ACIF parameter file

CC=YES
CCTYPE=Z
CONVERT=NO
CPGID=850
FILEFORMAT=STREAM,(NEWLINE=X'0A')
INPUTDD=C:\temp\billing_input.txt
OUTPUTDD=C:\temp\billing_input.txt.out
RESTYPE=NONE
INPEXIT=C:\Program Files\IBM\OnDemand for Windows\V9.0\exits\acif\asciinp.dll

Important: Specify the complete path in the inpexit, indxexit, resexit, or outexit
parameters. Nothing is more frustrating than trying to debug an exit that is never called
because another exit with the same name is started because of the PATH environment
variable.

Another method is to run arsload with the -i option, which runs only the indexer and does not
load any files. In this case, it is not necessary to add INPUTDD or OUTPUTDD to the indexing
parameters in the application. Running arsload with the -i option creates the .ind and .out
files, and leaves them on the system for you to view.

11.3 OS/390 indexer exits

The OS/390 indexer can be used to extract index data from and generate index data about
line data and AFP reports. In addition, other data types, such as TIFF images, can be
captured by using the anystore exit. The OS/390 indexer is available on the z/OS platform for
all versions and on the AIX platform beginning with Content Manager OnDemand V9.0. The
OS/390 indexer supports the following exits to assist with indexing and loading documents
into Content Manager OnDemand:
 The ANYSTORE exit (ANYEXIT) can be used to capture any type of data. The exit is
responsible for reading the load file and returning the index values and documents to the
indexer. A sample exit is provided that loads TIFF images.
 The INPUT exit (INPEXIT) can be used with line print data. It allows the load file contents
to be modified by the exit before they are stored in Content Manager OnDemand.
 The INDEX exit (INDXEXIT) can be used with any data type. It allows the index values for a
document to be modified before they are stored in Content Manager OnDemand.

248 IBM Content Manager OnDemand Guide

11.3.1 ANYEXIT exit
ANYEXIT is the anystore exit, which captures any type of data. The exit reads the data to be
captured, breaks it into documents, and determines the index values. The sample anystore
exit captures TIFF images by using a pre-generated set of indexing instructions that are read
from a separate file.

The anystore batch capture exit can be used to provide all segment and index data to the
report capture program. This exit program is called from the report capture process.

The exit is called dynamically during the capture process. The capture program calls the exit
when the indexing instructions for the application include the ANYEXIT parameter. The report
administrator provides a program name for the anystore exit.

The report capture program expects the anystore exit to pass back all segment data and the
associated index information. The capture program performs only the data management
functions that are required for the capture process (document compression, document store,
index management and store, and so on).

A sample COBOL exit is provided in ARSEXANY, which is in member

SARSINST(ARSEXANY) with the COBOL copybook ARSANYBK. A sample C exit is
provided in ARSECANY, which is in member SARSINST(ARSECANY) with the C header files
ARSANYBH and ARSZ390H.

11.3.2 INPEXIT exit

INPEXIT is the input exit, which is provided to allow more processing of the report input before
the report is stored. This exit can be used only when the INDEXSTYLE is not set to AFP and
when the ANYEXIT is not specified. The exit is called dynamically during the report capture
process. The report capture routine calls the exit when the indexing parameters specify an
input exit name in the INPEXIT parameter.

The report administrator provides a program name for this parameter.

No restrictions exist for the type of processing that can be performed in an input exit, except
that the exit must pass the standard parameter list back to the report capture program. Values
must be supplied for all parameters.

Beginning with Content Manager OnDemand for z/OS V8.4 or later, a line print file can have a
fixed record length that is greater than 512 or a variable record length. To support this
capability, a new parameter format is provided. The old parameter format is still supported for
compatibility with earlier versions.

To lean more about how to create an input exit, the details of the new parameter format, and
how Content Manager OnDemand determines whether to use the old or new parameter
format, see IBM Content Manager OnDemand Version 9 Release 5 - Indexing Reference,
SC19-3354.

11.3.3 INDXEXIT exit

INDXEXIT is the index exit, which is provided to allow the report indexes to be modified before
insertion into the application group data table. This exit can be used with any type of report
that is captured by the OS/390 indexer. The exit is called dynamically during the capture
process. The capture program calls the exit when the indexing instructions for the application
include the INDXEXIT parameter.

Chapter 11. Exits 249

 The report administrator provides a program name for the index exit.

No restrictions exist for the type of processing that can be performed in an index exit, except
that the exit must pass the standard parameter list back to the capture program. A sample
COBOL exit is provided in ARSEXNDX, with the COBOL copybook ARSINDBK. A sample C
exit is provided in ARSECNDX with the C header file ARSINDBH.

For more information about the OS/390 indexer, see IBM Content Manager OnDemand for
z/OS and OS/390 - Indexing Reference, SC27-1375.

11.4 System administration

In this section, we describe exits that are used for system administration: system message
logging and server printer configuration. These exits are in the bin directory of the Content
Manager OnDemand installation.

11.4.1 System log exit for Multiplatforms

The Content Manager OnDemand system log is a tool that is used by administrators. You can
use the Content Manager OnDemand Administrator Client to configure Content Manager
OnDemand to record information, warning, and error messages in the system log. Content
Manager OnDemand records messages, such as when users log on and log off the system.
Content Manager OnDemand also records messages for application group activity, such as
when clients query and retrieve data. Each operation that is performed by a user that involves
a connection to the Content Manager OnDemand server can be logged. The detail that is
captured within the system log can be configured so that only certain messages are retained,
and other messages can be discarded.

In addition, you can configure Content Manager OnDemand to send these messages to the
arslog exit. The system log exit is supplied in the arslog file that is in the bin directory of the
Content Manager OnDemand installation root for each platform. If the arslog file is opened in
a text editor, it contains comments that provide a brief description of the exit and the order of
the parameters that Content Manager OnDemand supplies to this exit. By default, the system
log exit is not initialized within Content Manager OnDemand. Therefore, if you edit the arslog
file to capture information, the exit does not run automatically.

To activate the system log exit, complete the following steps:

1. Start the Administrator Client and log on to the server on which you intend to use the
system logging exit.
2. Right-click the name of the server in the list and select System Parameters, as shown in
Figure 11-1 on page 251.

250 IBM Content Manager OnDemand Guide

 Figure 11-1 Select Content Manager OnDemand system parameters

3. To choose a User Exit Logging option, select the option.

Tip: The arslog exit file is run by the same user that owns the arssockd process that
calls this exit. A common reason for receiving no response from this exit is access
permissions on either the arslog file itself or files and directories that are accessed
within arslog.

Content Manager OnDemand provides an exit for each of the four system logging event
points. Use these exits to filter the messages and act when a particular event occurs. For
example, you can provide a user exit program that sends a message to a security
administrator when an unsuccessful logon attempt occurs.

System log exit samples

To demonstrate the common uses for the system log exit, we provide two typical examples:
 Capturing failed logon attempts (AIX)
 Notifying another system when a load completes (AIX)

For simplicity, we do not demonstrate the system log exits across all supported platforms. We
recognize that the scripting languages between platforms vary, but the principles that we
describe here are uniform across all supported platforms; only the syntax differs.

Capturing failed logon attempts (AIX)

Example 11-4 on page 252 is an extract from a simple system logging exit that captures
message code 31 (a failed logon attempt) and writes the user ID that was used and
information about the network address of this user to a file. In this case, the file name is a
combination of the system date and the string failedlogon.log. This system log exit writes
all of the failed logon attempts for each day to a file that can then be sorted and analyzed by
other utilities to alert for possible security risks.

Chapter 11. Exits 251

 Example 11-4 Capturing failed logon attempts (AIX)
# $1 - OnDemand Instance Name
# $2 - Time Stamp
# $3 - Log Identifier
# $4 - Userid
# $5 - Account
# $6 - Severity
# $7 - Message Number
# $8 - Message Text
#
case $7 in
31) echo $4 $8 >> /home/archive/`date +"%d-%m-%Y"`failedlogon.log;;
*) echo $@ > /dev/null;;
esac

exit 0

For the exit sample that is provided in Example 11-4, we also provided a small sample of what
the output of this exit might look like (Example 11-5). For example, you can see in the output
that several unsuccessful attempts were made from the same machine and different user IDs
were used for each attempt. In this example, by adding parameter 2 ($2) to the output and
resorting the file, we can further establish the times of these attempts.

Example 11-5 Sample exit output

ADMIN Failed login: GB55102K3.myServer.ibm.com 9.9.9.9
MARTIN Failed login: GB55102K3.myServer.ibm.com 9.9.9.9
FRED Failed login: GB55102K3.myServer.ibm.com 9.9.9.9
USER1 Failed login: GB55102K3.myServer.ibm.com 9.9.9.9
USER2 Failed login: GB55102K3.myServer.ibm.com 9.9.9.9

Notifying another system when a load completes (AIX)

This sample is used in a production environment where the number of load jobs that are sent
to Content Manager OnDemand must be controlled so that the next load job is sent only when
the previous load job completed successfully. We use this exit in this example because a
limited amount of disk space is available in the location on the Content Manager OnDemand
server where the load files are received from the remote machine. And, the load files are
large.

Example 11-6 shows how the exit collects virtually all of the available information when it
receives message number 87 (a successful load). This information is then used as the input
for another script, which notifies the remote machine that the load is complete and the next
report file can be sent.

Example 11-6 Controlling load jobs (AIX)

# $1 - OnDemand Instance Name
# $2 - Time Stamp
# $3 - Log Identifier
# $4 - Userid
# $5 - Account
# $6 - Severity
# $7 - Message Number
# $8 - Message Text
#

252 IBM Content Manager OnDemand Guide

 # if [ $6 = "3" ]; then
# print $@ >> /home/archive/InfoMsg.log
# fi

case $7 in
#
# msg num 87 is a successful load
#
87) echo "Instance : $1" >> /arsacif/companyx/arslog.out
echo "Time Stamp : $2" >> /arsacif/companyx/arslog.out
echo "Log Identifier : $3" >> /arsacif/companyx/arslog.out
echo "Userid : $4" >> /arsacif/companyx/arslog.out
echo "Account : $5" >> /arsacif/companyx/arslog.out
echo "Severity: $6" >> /arsacif/companyx/arslog.out
echo "Message Number: $7" >> /arsacif/companyx/arslog.out
echo "Message Text : $8" >> /arsacif/companyx/arslog.out
/arsacif/companyx/control_file.scr "$@" >> /arsacif/companyx/arslog.out ;;
*) ;;
esac

exit 0

Tips: For more information about the codes for each message type that is logged in the
system log, see Chapter 2, “Common Server Messages”, in IBM Content Manager
OnDemand - Messages and Codes, SC27-1379. For example, message number 87 is
listed as ARS0087I.

11.4.2 System log exit for z/OS

Content Manager OnDemand can be configured to record information, warning, and error
messages. You can set up Content Manager OnDemand to record these messages by using
the system log exit that is named the ARSLOG installation exit. The implementation of the
system log exit on z/OS differs from the implementation on Multiplatforms. Like other z/OS
exits, it uses the MVS Dynamic Exit Facility.

You configure the system log exit with the Administrator Client in the System Parameters
window (see Figure 11-2 on page 254).

Chapter 11. Exits 253

 Figure 11-2 System Parameters window with User Exit Logging selected

Select the options for the system logging and set up the exit. The sample in Example 11-7
routes the messages to the system log with the write to operator (WTO) macro.

Example 11-7 System log exit setup sample

ARSLOG title 'Issue a message to syslog' 00010000
****************** START OF MODULE SPECIFICATIONS ******************* 00020000
* * 00030000
* * 00040000
* ==> OD/390 - 5655-H39 <== * 00050007
* * 00060000
* Module Name: ARSLOG * 00070000
* * 00080000
* Descriptive Name: Issue a message to syslog * 00090000
* * 00100000
* Status: Version ? Release ? * 00110000
* * 00120000
* Function: This routine issues a message to the SYSLOG * 00130000
* * 00140000
* Copyright: 5655-H39 (C) Copyright IBM Corp. 2013 * 00150007
* Licensed Materials-Property of IBM * 00160000
* See Copyright instructions. * 00170000
* * 00180000
* Notes: * 00190000
* * 00200000
* Restrictions: None * 00210000
* * 00220000

254 IBM Content Manager OnDemand Guide

* Register * 00230000
* Convention: R1 points to the Parameter list * 00240000
* R12 base register 00250000
* * 00260000
* Patch Label: PSPACE * 00270000
* * 00280000
* Input: Parameter list pointed to by Register 1 * 00290000
* Parameter list contains addresses of: * 00300000
* - message length * 00310000
* - message text * 00320000
* * 00330000
* Output: None * 00340000
* * 00350000
* Return codes: * 00360000
* * 00370000
* NORMAL: R15 = return code from WTO * 00380000
* * 00390000
* Exits: Return to caller via BR 14 * 00400000
* * 00410000
* External References: * 00420000
* * 00430000
* Change Activity: See below * 00440000
* * 00450000
* Ver Rel Mod Date Description of Change * 00460000
* ___________ ________ _______________________________________ * 00470000
* 0? 0? 00 04/05/00 Release ?.? * 00480000
* * 00490000
******************** END OF MODULE SPECIFICATIONS ******************* 00500000
ARSLOG csect 00510000
ARSLOG rmode any 00520000
ARSLOG amode 31 00530000
using *,r15 00540000
b pastcopy 00550000
dc C'ARSLOG &sysdate' 00560000
dc C'5622-662 (C) COPYRIGHT IBM CORP. 2013' 00570000
dc C'ALL RIGHTS RESERVED' 00580000
dc C'LICENSED MATERIALS-PROPERTY OF IBM' 00590000
pastcopy ds 0h 00600000
stm 14,12,12(r13) 00610001
lr r12,r15 00620000
lr r2,r1 00630000
using plist,r2 00640000
drop r15 00650000
using ARSLOG,r12 00660000
storage OBTAIN,length=workl,loc=ANY,cond=YES 00670000
ltr r15,r15 00680000
jnz bagit 00690000
st r13,4(,r1) 00700000
st r1,8(,r13) 00710000
lr r13,r1 00720000
using workarea,r13 00730000
* 00740000
* Determine the message length 00750005
* 00760000
slr r1,r1 Number of bytes 00770005
l r15,msgtxta get starting address 00780005
nulloop ds 0h 00790006
cli 0(r15),x'00' Is it zero? 00800005
je nomore Yes - quit 00810005
la r1,1(,r1) Bump count 00820005

Chapter 11. Exits 255

 la r15,1(,r15) bump address 00830005
j nulloop And try next 00840005
nomore ds 0h 00850005
lr r3,r1 Save length of message 00860005
mvc msgtxt+2(3),=c'XXX' Set the prefix 00870007
la r14,msgtxt+5 Start to place number 00880005
l r15,msgnum Get start of message number 00890005
numloop ds 0h 00900005
cli 0(r15),x'00' Null? 00910005
je nomove 00920005
mvc 0(0,r14),0(15) move it 00930005
la r14,1(,r14) next destination 00940005
la r15,1(,r15) next source 00950005
j numloop go do next 00960005
nomove ds 0h 00970005
l r15,sev Get severity 00980005
cli 0(r15),c'1' Is it Alert 00990005
jne tryerror No skip 01000005
mvi 0(r14),c'E' Set error severity 01010006
j donesev 01020005
tryerror ds 0h 01030005
cli 0(r15),c'2' "Error" severity? 01040005
jne trywarn No - skip 01050005
mvi 0(r14),c'E' Set error 01060005
j donesev 01070006
trywarn ds 0h 01080005
cli 0(r15),c'3' Is it Warning 01090006
jne setinfo 01100005
mvi 0(r14),C'W' Set Warning 01110005
j donesev 01120005
setinfo ds 0h 01130005
mvi 0(r14),c'I' Indicate info 01140005
donesev ds 0h 01150005
mvi 1(r14),c' ' Put in blank 01160005
la r14,2(,r14) Skip 01170005
01180005
c r3,=f'60' More than 60 chars 01190005
jnh singlwto No - issue it 01200005
lhi r3,60 Only first 60 chars 01210005
01220005
* We only need to issue a single WTO 01230005
01240005
singlwto ds 0h 01250005
la r4,msgtxt+2 Get start of text 01260005
lr r15,r14 Get where we stopped 01270005
sr r15,r4 Get how much we've done 01280005
ar r15,r3 add length of text 01290005
stcm r15,b'0011',msgtxt Set the length 01300005
bctr r3,0 subtract 1 01310005
l r15,msgtxta Get source address 01320005
ex r3,mvcins Move it 01330005
01340000
mvc wtoe,wto1 init the execute form 01350007
la r3,msgtxt 01360005
slr r0,r0 01370000
wto text=(r3),mf=(E,wtoe) 01380005
j exit exit 01390000
01400000
02250000
exit ds 0h 02260000

256 IBM Content Manager OnDemand Guide

 lr r1,r13 02270000
l r2,4(r13) 02280002
storage RELEASE,length=workl,addr=(r1) 02290003
lr r13,r2 02300002
drop r13 02310000
02320000
bagit ds 0h 02330000
lm 14,12,12(r13) 02340001
br r14 02350000
psize equ ((*-ARSLOG+99)/100)*5 02360000
dc C'PATCH AREA - ARSLOG &sysdate' 02370000
pspace dc 25s(*) 02380000
org pspace 02390000
dc ((psize+1)/2)s(*) 02400000
02410000
02420000
mvcins mvc 0(0,r14),0(r15) 02430000
02450000
wto1 wto text=, +02460000
desc=(6), +02470000
mcsflag=(BUSYEXIT), +02480000
routcde=(11), +02490000
mf=L 02500000
wto1l equ *-wto1 02510000
ltorg 02520005
02530005
workarea dsect 02870000
rsa ds 18f 02880000
wtoe ds cl(wto1l) 02890006
msgtxt ds cl(72) 02900005
workl equ *-workarea 02910000
02920000
plist dsect 02930000
instance ds a 02940005
tstamp ds a 02950005
logrec ds a 02960005
userid ds a 02970005
acct ds a 02980005
sev ds a 02990005
msgnum ds a 03000005
msgtxta ds a 03010005
03020005
yregs , 03030007
iezwpl 03040005
end , 03050005

When the exit routine is assembled and link-edited to a library, it must be associated with the
exit in one of two ways:
 Use the exit statement in the PROGXX parmlib member. For more information about the
PROGXX parmlib member, see z/OS MVS Initialization and Tuning Reference,
SA22-7592.
 Use the SETPROG EXIT operator command. For more information about the SETPROG EXIT
command, see z/OS MVS System Commands, SA22-7627.

To activate the exit routine, run the following command:

SETPROG EXIT,ADD,EXITNAME=ARSLOG,MODENAME=ARSLOG, DSN=TEAM5.LOADLIB

The exit was link-edited to a normal library that is not AFP-authorized.

Chapter 11. Exits 257

11.4.3 Print exit for Multiplatforms
A Content Manager OnDemand printer is an interface between the user and a print device
that is controlled by a server. Multiple methods are available to print a document that is stored
in Content Manager OnDemand:
 Local printing: This function is accomplished through a local area network (LAN)-attached
personal computer printer.
 Server printing: This function is accomplished by submitting a print job to the print server
queue, for example an IBM Infoprint Server print queue. Infoprint is an intelligent printer
driver that provides AFP capabilities for Content Manager OnDemand servers.

A server print device can be physically connected to the library server or attached to another
workstation in the network. Server print devices are managed by Infoprint.

Content Manager OnDemand provides a print exit for Multiplatforms that can be used only for
documents that are printed through a server printer.

Two print exits are available for Multiplatforms, which are in the bin directory of the Content
Manager OnDemand installation root for each platform:
 arsprt: Content Manager OnDemand User Exit Printing Facility
 arsrdprt: Content Manager OnDemand User Exit Printing Facility for Report Distribution

If you open either of the files in a text editor, you can see that they contain comments that
provide a brief description of the exit and the order of the parameters that Content Manager
OnDemand gives to this exit.

Example 11-8 shows an arsprt file, which updates application group indexes for a certain
document type each time it is sent to a server printer. This example is from an actual
customer where the requirement was for Content Manager OnDemand to keep a record of
when a document is reprinted. This file is created by using the print exit to update the indexes
of a document to show the last time that the document was reprinted and a counter is
incremented to log the number of times the document was reprinted. Comments are inserted
into the sample script in Example 11-8 that explain each part of the script. The customer
name and the IP addresses are either altered or removed.

Example 11-8 Sample arsprt print exit file

#!/bin/ksh
#
# arsprt - OnDemand User Exit Printing Facility
#
# 5622-662 (C) COPYRIGHT IBM CORPORATION 2013
# All Rights Reserved
# Licensed Materials - Property of IBM
#
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#
# This program sample is provided on an as-is basis.
# The license of the OnDemand product is free to copy, revise,
# modify, and make changes to this sample program
# as see fit.
#
# Function added to update a document each
# time a reprint is done. Index 'reprint' is updated with a 'I'
# and index 'log' is updated with a date and a counter of 001 (if the
# document has already been reprinted, the counter is added up by 001.

258 IBM Content Manager OnDemand Guide

set -a
set -u
set -m
#set -x

##################
# 3 stmt's added #
# for debugging #
##################
#RANDOM=$$
#set -x
#exec 2> /usr/lpp/ars/bin/debug1.log.$RANDOM

RM=/bin/rm
SED=/bin/sed

OS=$(uname)

if [[ ${OS} = AIX ]] ; then

BASE_DIR=/usr/lpp/ars/bin
elif [[ (${OS} = HP-UX) || (${OS} = SunOS) ]] ; then
BASE_DIR=/opt/ondemand/bin
ARSPRT_HOSTNAME=
else
print "Cannot determine operating system"
exit 1
fi

#
# $1 - Printer Queue Name
# $2 - Copies
# $3 - Userid
# $4 - Application Group Name
# $5 - Application Name
# $6 - Application Print Options
# $7 - Filename to Print

#
# NOTE: It is up to this script to make sure the file is deleted.
# example( -r option on /bin/enq )
#
FILE=$7
OPTS_FILE=${FILE}.opts
NOTES_FILE=${FILE}.notes
if [[ -f ${OPTS_FILE} ]] ; then
DEL=1
PRT_OPTIONS="-o PASSTHRU=fax_file-${FILE}-"
#
# Since I am faxing, make sure messages are not produced.
# If debugging is needed, then this parameter should be blank.
#
#EXTRA_OPTIONS="-o MSGCOUNT=0"
EXTRA_OPTIONS="-o MSGCOUNT=0"
else
DEL=0
PRT_OPTIONS=
EXTRA_OPTIONS=
fi

Chapter 11. Exits 259

 TITLE=$(print "$3 $4 $5" | ${SED} 's/-/ /g')

if [[ ${OS} = AIX ]] ; then

/bin/enq -r -P "$1" -N $2 -T "${TITLE}" $6 ${EXTRA_OPTIONS} ${PRT_OPTIONS} ${FILE}
else
${BASE_DIR}/lprafp -p "$1" -s "${ARSPRT_HOSTNAME}" -o "COPIES=${2}" -o
"JOBNAME=${TITLE}" -o "TITLE=${TITLE}" $6 ${EXTRA_OPTIONS} ${PRT_OPTIONS} ${FILE}
fi

RC=$?

if [[ ${RC} = 0 ]] ; then
if [[ ${OS} != AIX ]] ; then
${RM} -f ${FILE}

else
####################################
# Test if filename ends up with .0 #
# If not,skip around code to update#
# index. This prevents update of #
# same index several times as only #
# one .cntl file is created #
# when server print is made for #
# multiple documents and this #
# script is called one time for #
# each doc to print. #
####################################
ext=$7
ext=${ext##*.}
if [[ ${ext} = 0 ]] ; then
####################################
# Compute .cntl filname from #
# supplied parameter $7 #
####################################
fil=$7
mine=${fil%.*}.cntl
####################################
# Double check if .cntl file exist #
####################################
if test ! -f $mine
then echo "File $mine not found"
exit 1
fi

####################################
# Set static variables #
####################################
host=9.99.99.99
nohit=no

applgrp1=ICAlog
folder1=ICAlog

applgrp2=applg2
folder2=folder2

applgrp3=applg3
folder3=folder3
####################################

260 IBM Content Manager OnDemand Guide

 # Read info from .cntl file #
####################################
cat $mine |grep -v APPLICATION|while read a1 a2 a3 a4 a5 a6 a7 a8 a9
do
####################################
# Get the application group name #
####################################
applgrp=$a2
applgrp=${applgrp##*=}
####################################
# Set the folder name depending on #
# what the application group name #
# is #
####################################
if [[ ${applgrp} = ${applgrp1} ]]
then
folder=$folder1
else
if [[ ${applgrp} = ${applgrp2} ]]
then
folder=$folder2
else
if [[ ${applgrp} = ${applgrp3} ]]
then
folder=$folder3
####################################
# Not an application group we are #
# looking for. Set nohits=yes to #
# skip to remove the .cntl file #
####################################
else
nohit=yes
fi
fi
fi
####################################
# If nohit=no, get Account-number and#
# log info #
####################################
if [[ ${nohit} = no ]]
then
####################################
# Get Account Number #
####################################
account-number=$a4
account-number=${account-number##*=}
####################################
# Get log info. If first time, #
# then set count=001 and current #
# date #
####################################
log=$a8
log=${log##*=}
if [[ $log = "" ]]
then
log=001
####################################
# If not first time for reprint, #
# then add up old count by 1 #
####################################

Chapter 11. Exits 261

 else
let log=$log+001
typeset -Z3 log
fi
####################################
# Set date after log count #
####################################
datum=`date +%Y-%m-%d`
blank=" "
####################################
# Update this document with count #
# of reprints and current date #
####################################
arsdoc update -h $host -g $applgrp -f $folder -n log="$log$blank$datum" -n
reprint=I -u admin -p ondemand -i "where account-number='$account-number'" -v
fi
####################################
# Done, remove the .cntl file #
####################################
done
rm $mine
fi

fi
else
(
if [[ ${OS} = AIX ]] ; then
echo /bin/enq -r -P "$1" -N $2 -T "${TITLE}" $6 ${EXTRA_OPTIONS} ${PRT_OPTIONS}
${FILE}
else
echo ${BASE_DIR}/lprafp -p "$1" -s "${ARSPRT_HOSTNAME}" -o "COPIES=${2}" -o
"JOBNAME=${TITLE}" -o "TITLE=${TITLE}" $6 ${EXTRA_OPTIONS} ${PRT_OPTIONS} ${FILE}
fi

echo "$(date)-->OnDemand Failed Print File >${FILE}< to Queue >$1<"

) >/dev/console
exit ${RC}
fi

#
# If there is an options file, wait until the file has been
# printed before removing it.
#
if [[ ${DEL} != 0 ]] ; then
while(( 1 ))
do
if [[ -f "${FILE}" ]] ; then
sleep 30
else
${RM} -f ${OPTS_FILE} ${NOTES_FILE}
break
fi
done
fi
exit 0

262 IBM Content Manager OnDemand Guide

11.5 Customized functions (Multiplatforms and z/OS only)
The user exits provide customized ways to perform tasks in Content Manager OnDemand.
You can use a user exit to customize logins, retrieve data from external locations, or send a
notification when a document is loaded. Programming of the user exits is an IBM Lab
Services offering; for more information, contact IBM Lab Services.

You can also use the sample exit source code to write your own exits. In this section, we
describe each sample exit that is provided in the standard Content Manager OnDemand
installation.

The sample source code for the Content Manager OnDemand user exits is provided for all of
the platforms. They are placed in the directories or libraries of Content Manager OnDemand
that are listed in Table 11-1. These sample user exit modules provide a skeleton for you to
program the exits.

Table 11-1 Exits and their initial locations

Module Location

arsuload Content Manager OnDemand V8.5:

arsuprep  Windows: C:\Program Files\IBM\OnDemand for Windows\bin\exits
arsuupdt  AIX: /usr/lpp/ars/bin/exits
arsutbl  Solaris, HPUX, and Linux: /opt/ondemand/bin/exits
 z/OS: /usr/lpp/ars/exits or ARS.V8R5M0.SARSINST

Content Manager OnDemand V9.0:

 Windows: C:\Program Files\IBM\OnDemand for Windows\V9.0\bin\exits
 AIX, Solaris, and HPUX: /opt/IBM/ondemand/V9.0/bin/exits
 Linux and Linux on System z: /opt/ibm/ondemand/V9.0/bin
 z/OS: /usr/lpp/ars/V9R0M0/exits or ARS.V9R0M0.SARSINST

Content Manager OnDemand V9.5:

 Windows: C:\Program Files\IBM\OnDemand for Windows\V9.5\bin\exits
 AIX, Solaris, and HPUX: /opt/IBM/ondemand/V9.5/bin/exits
 Linux and Linux on System z: /opt/ibm/ondemand/V9.5/bin
 z/OS: /usr/lpp/ars/V9R5M0/exits or ARS.V9R5M0.SARSINST

The header file provides information about how to turn on the user exits. If the information is
not specified in the header file, place the compiled user exit program into the bin/exits
directory of the Content Manager OnDemand installation root.

The source code must be compiled before you use it. For UNIX platforms, you can compile
the source code by using the sample makefile that is provided. The makefile is in the same
exits directory as the sample exits source code.

Table 11-2 provides the functions and usage of the user exit modules.

Table 11-2 User exits module

Module Function Usage

arsuload LOADEXIT To obtain load information for notification

arsuprep PREPEXIT To preprocess document data before document retrieval

arsuupdt ARSUUPDT To alter parameters when document data is captured by ARSLOAD

arsutbl TBLSPCRT To customize the creation of table spaces, tables, and indexes

Chapter 11. Exits 263

11.5.1 User exit header file (arscsxit.h)
Before you write the user exit, it is important to study the header file arscsxit.h. This file is in
the same exits directory as the sample user exit source code. This file contains the structure
and function declarations for the customized Content Manager OnDemand user exits. Also,
instructions are included to activate the user exit after it is compiled.

The first part of the header file is a declaration of all of the structures and variables that are
used. Example 11-9 shows several of the common structures that are used in the functions
declarations.

Example 11-9 Common structure that is defined in the arscsxit.h header file
/*********************************************************************/
/* COMMON STRUCTURES */
/*********************************************************************/
#define ARCCSXIT_MAX_SRVR_MESSAGE_SIZE 1024

#if defined(AIX) || defined(HPUX) || defined(OS390) || defined(CICS)

#define ARCCSXIT_PATH_MAX 1023
#elif defined(LINUX)
#define ARCCSXIT_PATH_MAX 4096
#elif defined(SUNOS) || defined(__OS400__)
#define ARCCSXIT_PATH_MAX 1024
#elif defined(WIN32)
#define ARCCSXIT_PATH_MAX 260
#endif

typedef struct _ArcCSXitApplGroup

{
char *name;
ArcI32 agid;
char *agid_name;
} ArcCSXitApplGroup;

typedef struct _ArcCSXitApplGroupU

{
ArcChar *name;
ArcI32 agid;
ArcChar *agid_name;
} ArcCSXitApplGroupU;

typedef ArcU8 ArcCSXitDocType;

#define ARCCSXIT_DOC_TYPE_AFP (ArcCSXitDocType) 0x41
#define ARCCSXIT_DOC_TYPE_BMP (ArcCSXitDocType) 0x42
#define ARCCSXIT_DOC_TYPE_EMAIL (ArcCSXitDocType) 0x45
#define ARCCSXIT_DOC_TYPE_GIF (ArcCSXitDocType) 0x47
#define ARCCSXIT_DOC_TYPE_JFIF (ArcCSXitDocType) 0x4A
#define ARCCSXIT_DOC_TYPE_DJDE (ArcCSXitDocType) 0x4B
#define ARCCSXIT_DOC_TYPE_LINE (ArcCSXitDocType) 0x4C
#define ARCCSXIT_DOC_TYPE_META (ArcCSXitDocType) 0x4D
#define ARCCSXIT_DOC_TYPE_NONE (ArcCSXitDocType) 0x4E
#define ARCCSXIT_DOC_TYPE_ODDOC (ArcCSXitDocType) 0x4F
#define ARCCSXIT_DOC_TYPE_PCX (ArcCSXitDocType) 0x50
#define ARCCSXIT_DOC_TYPE_PDF (ArcCSXitDocType) 0x52
#define ARCCSXIT_DOC_TYPE_PNG (ArcCSXitDocType) 0x51
#define ARCCSXIT_DOC_TYPE_SCS (ArcCSXitDocType) 0x53
#define ARCCSXIT_DOC_TYPE_SCS_EXT (ArcCSXitDocType) 0x58
#define ARCCSXIT_DOC_TYPE_TIFF (ArcCSXitDocType) 0x54
#define ARCCSXIT_DOC_TYPE_USRDEF (ArcCSXitDocType) 0x55

264 IBM Content Manager OnDemand Guide

typedef ArcU8 ArcCSXitDocFormat;
#define ARCCSXIT_DOC_FORMAT_FIXED (ArcCSXitDocFormat) 0x00
#define ARCCSXIT_DOC_FORMAT_VARIABLE (ArcCSXitDocFormat) 0x01
#define ARCCSXIT_DOC_FORMAT_STREAM (ArcCSXitDocFormat) 0x02

typedef ArcU8 ArcCSXitCarCtl;

#define ARCCSXIT_CC_ANSI (ArcCSXitCarCtl) 'A'
#define ARCCSXIT_CC_MACHINE (ArcCSXitCarCtl) 'M'
#define ARCCSXIT_CC_NONE (ArcCSXitCarCtl) 'N'

typedef ArcU8 ArcCSXitPrMode;

#define ARCCSXIT_PRMODE_NONE (ArcCSXitPrMode) 'N'
#define ARCCSXIT_PRMODE_SOSI1 (ArcCSXitPrMode) '1'
#define ARCCSXIT_PRMODE_SOSI2 (ArcCSXitPrMode) '2'
#define ARCCSXIT_PRMODE_SOSI3 (ArcCSXitPrMode) '3'

typedef struct _ArcCSXitAppl

{
char *name;
ArcI32 aid;
ArcCSXitDocType doc_type;
ArcCSXitDocFormat doc_fmt; /* Document Format for Linedata */
union
{
ArcI32 fixed; /* Fixed - Record Length */
char streamÝ17¨; /* Stream - Character Delimiters */
} u;
ArcU8 trc_present; /* 0 = no, 1 = yes */
ArcI32 line_count; /* Lines per page for line data */
ArcI32 code_page; /* Code Page for line data */
ArcCSXitCarCtl cc_type; /* CC type for line data */
ArcCSXitPrMode prmode; /* PRMode for line data */
} ArcCSXitAppl;

typedef struct _ArcCSXitApplU

{
ArcChar *name;
ArcI32 aid;
ArcCSXitDocType doc_type;
ArcCSXitDocFormat doc_fmt; /* Document Format for Linedata */
union
{
ArcI32 fixed; /* Fixed - Record Length */
ArcChar streamÝ17¨; /* Stream - Character Delimiters */
} u;
ArcU8 trc_present; /* 0 = no, 1 = yes */
ArcI32 line_count; /* Lines per page for line data */
ArcI32 code_page; /* Code Page for line data */
ArcCSXitCarCtl cc_type; /* CC type for line data */
ArcCSXitPrMode prmode; /* PRMode for line data */
} ArcCSXitApplU;

typedef ArcU8 ArcCSXitFieldType;

#define ARCCSXIT_FIELD_TYPE_BIGINT (ArcCSXitFieldType) 0x42
#define ARCCSXIT_FIELD_TYPE_DATE (ArcCSXitFieldType) 0x61
#define ARCCSXIT_FIELD_TYPE_DATETIME (ArcCSXitFieldType) 0x62
#define ARCCSXIT_FIELD_TYPE_DECFLOAT16 (ArcCSXitFieldType) 0x38
#define ARCCSXIT_FIELD_TYPE_DECFLOAT34 (ArcCSXitFieldType) 0x39
#define ARCCSXIT_FIELD_TYPE_DECIMAL (ArcCSXitFieldType) 0x44

Chapter 11. Exits 265

 #define ARCCSXIT_FIELD_TYPE_INTEGER (ArcCSXitFieldType) 0x49
#define ARCCSXIT_FIELD_TYPE_SMALLINT (ArcCSXitFieldType) 0x4E
#define ARCCSXIT_FIELD_TYPE_STRING (ArcCSXitFieldType) 0x53

typedef ArcU8 ArcCSXitFieldTypeQual;

#define ARCCSXIT_FIELD_TYPE_QUAL_BASE (ArcCSXitFieldTypeQual) 0x42
#define ARCCSXIT_FIELD_TYPE_QUAL_DATETIME (ArcCSXitFieldTypeQual) 0x43
#define ARCCSXIT_FIELD_TYPE_QUAL_DATE (ArcCSXitFieldTypeQual) 0x44
#define ARCCSXIT_FIELD_TYPE_QUAL_TIME (ArcCSXitFieldTypeQual) 0x54
#define ARCCSXIT_FIELD_TYPE_QUAL_TZ_DATETIME (ArcCSXitFieldTypeQual) 0x5A

typedef struct _ArcCSXitField

{
char *db_name;
ArcCSXitFieldType type;
ArcCSXitFieldTypeQual qual;
union
{
ArcI16 n;
ArcI32 i;
ArcI64 b;
double d;
char *str;
ArcDateTime dt;
ArcDecimal64 d64;
ArcDecimal128 d128;
} u;
} ArcCSXitField;

typedef struct _ArcCSXitFieldU

{
ArcChar *db_name;
ArcCSXitFieldType type;
ArcCSXitFieldTypeQual qual;
union
{
ArcI16 n;
ArcI32 i;
ArcI64 b;
double d;
ArcChar *str;
ArcDateTime dt;
ArcDecimal64 d64;
ArcDecimal128 d128;
} u;
} ArcCSXitFieldU;

typedef struct _ArcCSXitDocFields

{
ArcI32 flds_num;
ArcCSXitField *flds;
} ArcCSXitDocFields;

#define ARCCSXIT_DOCNAME_SIZE 11

typedef struct _ArcCSXitDocHandle

{
char nameÝARCCSXIT_DOCNAME_SIZE + 1¨;
ArcU32 doc_off;
ArcU32 doc_len;

266 IBM Content Manager OnDemand Guide

 ArcU32 comp_off;
ArcU32 comp_len;
} ArcCSXitDocHandle;

typedef struct _ArcCSXitDoc

{
ArcCSXitDocFields doc_flds;
ArcCSXitDocHandle doc_hndl;
} ArcCSXitDoc;

From the previous example, the ArcCSXitApplGroup structure consists of the application
group name, the application group identifier (agid), and the AGID name (agid_name). This
information is important because it indicates the input to the functions. Structures that are
specific to a function are also included in the header file.

In the following sections, we examine each exit and describe its usage.

11.5.2 Load exit

The load exit is used to send a notification after a document is loaded. The header file in
Example 11-10 shows the information that can be incorporated into the notification message.

Example 11-10 Header file of the load exit

/**********************************************************************/
/* LOADEXIT - Load Exit */
/* */
/* To activate the load exit, the arsuload dll must exist in the */
/* OnDemand exits installation directory. */
/* */
/* INPUT: load */
/* */
/* OUTPUT: */
/* None */
/* */
/* RETURN_CODE: */
/* 0 -> Successful */
/* Otherwise -> Failed */
/* */
/**********************************************************************/
typedef struct _ArsCSXitLoadExit
{
char *hostname; /* OnDemand Library Server Hostname */
char *load_id; /* Load Id */
ArcU32 deprecated; /* was bytes. Use report_bytes */
ArcU32 res_bytes; /* Number of resource bytes stored */
ArcCSXitApplGroup *appl_grp; /* Application Group Info */
ArcCSXitAppl *appl; /* Application Info */
char *file; /* File containing all rows */
char *user_def; /* User Specified string to load */
ArcCSXitField *reference; /* Reference column defined for ODF */
char *file_l; /* File containing rows in non-UTF8 */
ArcU32 cp; /* codepage file_l is in */
void **hndl; /* pointer to anchor for arsuload */
char ColDelim; /* Character used to delimit columns*/
ArcI64 report_bytes;/* Number of bytes in report */
char *instance; /* OD Instance name */
} ArsCSXitLoadExit;

Chapter 11. Exits 267

 ArcI32
ARSCSXIT_EXPORT
ARSCSXIT_API
LOADEXIT( ArsCSXitLoadExit *load );

You can use the sample exits program to insert the action that you prefer. The input to the
program is in the structure ArsCSXitLoadExit. This structure contains the load information,
such as the load identifier and the application group name. Based on the load information,
you decide whether to send a notification, to whom to send the notification, and the type of
information you want to provide when loading is successful.

Activating the load exit

To activate the exits, place the compiled exit program arsuload in the bin/exits directory of
the Content Manager OnDemand installation root.

Client retrieval preview exit

Use the client retrieval preview user exit to modify document data before the data is
presented to a client. This exit is called during the retrieval of a document.

You can use the client retrieval preview exit to add, remove, or reformat data before the
document is presented to the client, for example:
 You can remove pages from the document, such as banner pages, title pages, or all pages
except the summary page.
 You can remove specific words, columns of data, or other information from the document.
That is, you can omit (“white out”) sensitive information, such as salaries, social security
numbers, and birth dates.
 You can add information to the document, for example, a summary page, data analysis
information, and Confidential or Copy statements.
 You can reformat data that is contained in the document. For example, you can reorder the
columns of data.

The client retrieval preview exit point might be enabled for specific applications. However, to
enable the client retrieval preview exit for a specific application, ensure that the Use Preview
Exit option is selected on the Miscellaneous Options page of the application.

The input to the exit program is captured when the user tries to retrieve the document. Based
on the input, such as application group name and the indexes, you can then use your program
to create an output file with the name from pOutFileName.

Example 11-11 shows the header file of the client retrieval preview exit.

Example 11-11 Header file of client retrieval preview exit

/**********************************************************************/
/* PREPEXIT - Client Retrieval Preview Exit */
/* */
/* This exit is used to modify the contents of a document prior */
/* retrieving the document */
/* */
/* INPUT: */
/* pInFileName */
/* pOutFileName */
/* pUserParms */
/* pApplGrp */
/* pAppl */

268 IBM Content Manager OnDemand Guide

 /* pDoc */
/* */
/* OUTPUT: */
/* */
/* RETURN_CODE: */
/* 0 -> Successful */
/* Otherwise -> Failed */
/* */
/**********************************************************************/
typedef struct _ArsCSXitPrepExit
{
char *pUserid; /* Logged on userid */
char *pInFileName; /* File name for document data */
char OutFileName[ARCCSXIT_PATH_MAX + 1];
/* File name for modified data */
char *pUserParms; /* User defined parms from appl */
ArcCSXitApplGroup *pApplGrp; /* Appl Grp info */
ArcCSXitAppl *pAppl; /* Application info */
ArcCSXitDoc *pDoc; /* Doc handle, field info */
char *instance; /* OD Instance name */
} ArsCSXitPrepExit;

ArcI32
ARSCSXIT_EXPORT
ARSCSXIT_API
PREPEXIT( ArsCSXitPrepExit *prep );

For example, you can arrange it so that when a user retrieves a document from a particular
application group, you can check the name of the account number (the indexes from the Doc
handle) and place a watermark for that document. When the document is retrieved by the
user, the user sees the document with the watermark.

Activating the client retrieval preview exit

To activate the client retrieval preview exit, select the Use Preview Exit option on the
Miscellaneous Options page of an application and place the exit in the bin/exits directory of
the Content Manager OnDemand installation root. When the option is selected, the
user-written program is called any time that a request is made to retrieve a document.

Any information that is specified in the Parameters field is passed to the user-written program.
Place the arsuprep program in the bin/exits directory.

The client retrieval preview user exit can be enabled for all data types, except for None.

For more information, see the IBM Content Manager OnDemand for Multiplatforms -
Installation and Configuration Guide, SC18-9232.

11.5.3 Report specifications archive definition exit

Use the Content Manager OnDemand report specifications archive definition exit to change
several of the parameters that are used by Content Manager OnDemand when document
data is loaded by the ARSLOAD program. ARSUUPDT is a dynamic link library (DLL) module that is
written in the C programming language.

Chapter 11. Exits 269

 The first call modifies the names process for parameters, such as application group,
application, object server, storage node, DB field date format, and DB field name. The second
call modifies the indexing parameters and input file parameters. Example 11-12 shows the
header file of the report specifications archive definition exit.

Example 11-12 Header file of the report specifications archive definition exit
/**********************************************************************/
/* UPDTEXIT - Report Definition Update Exit */
/* */
/* This exit is for specialized applications and is not normally */
/* used. */
/* */
/* INPUT: */
/* pFileName */
/* Function */
/* ApplGrpName */
/* ApplName */
/* ObjServer */
/* StorageNode */
/* pJES */
/* IndexerParms */
/* CCType */
/* LRECL */
/* RECFM */
/* Delim */
/* instance */
/* */
/* OUTPUT: */
/* ApplGrpName */
/* ApplName */
/* ObjServer */
/* StorageNode */
/* IndexerParms */
/* CCType */
/* LRECL */
/* RECFM */
/* UpdateAppl */
/* Delim */
/* DbFieldName */
/* DbFieldDateFormat */
/* */
/* RETURN_CODE: */
/* 0 -> Successful */
/* Otherwise -> Failed */
/* */
/**********************************************************************/

#if defined(OS390)
typedef struct _ArsCSXitUpdtExit_JES
{
void *JES_SSS2p; /* pointer to SSS2 (SAPI SSOB ext) */
char JES_DDÝ8¨; /* DD name allocated to spool file */
} ArsCSXitUpdtExit_JES;
#endif

typedef struct _ArsCSXitUpdtExit

{
char *pFileName;
ArcI32 Function;

270 IBM Content Manager OnDemand Guide

 char ApplGrpNameÝARCCSXIT_MAX_NAME_SIZE + 1¨;
char ApplNameÝARCCSXIT_MAX_NAME_SIZE + 1¨;
char ObjServerÝARCCSXIT_MAX_SERVER_SIZE + 1¨;
char StorageNodeÝARCCSXIT_MAX_NAME_SIZE + 1¨;
void *pJES;
char IndexerParmsÝARCCSXIT_MAX_INDEXER_SIZE + 1¨;
ArcCSXitCarCtl CCType;
ArcI32 LRECL;
ArcCSXitDocFormat RECFM;
ArcI32 UpdateAppl;
char DelimÝARCCSXIT_MAX_DELIMITER_SIZE + 1¨;
char *instance;
char DbFieldNameÝARCCSXIT_MAX_DBCOL_NAME_SIZE + 1¨;
char DbFieldDateFormatÝARCCSXIT_MAX_DATEFMT_SIZE + 1¨;
} ArsCSXitUpdtExit;

typedef struct _ArsCSXitUpdtExitU

{
ArcChar *pFileName;
ArcI32 Function;
ArcChar ApplGrpNameÝARCCSXIT_MAX_NAME_SIZE + 1¨;
ArcChar ApplNameÝARCCSXIT_MAX_NAME_SIZE + 1¨;
ArcChar ObjServerÝARCCSXIT_MAX_SERVER_SIZE + 1¨;
ArcChar StorageNodeÝARCCSXIT_MAX_NAME_SIZE + 1¨;
void *pJES;
ArcChar IndexerParmsÝARCCSXIT_MAX_INDEXER_SIZE + 1¨;
ArcCSXitCarCtl CCType;
ArcI32 LRECL;
ArcCSXitDocFormat RECFM;
ArcI32 UpdateAppl;
ArcChar DelimÝARCCSXIT_MAX_DELIMITER_SIZE + 1¨;
ArcChar *instance;
ArcChar DbFieldNameÝARCCSXIT_MAX_DBCOL_NAME_SIZE + 1¨;
ArcChar DbFieldDateFormatÝARCCSXIT_MAX_DATEFMT_SIZE + 1¨;
} ArsCSXitUpdtExitU;

ArcI32
ARSCSXIT_EXPORT
ARSCSXIT_API
UPDTEXIT( ArsCSXitUpdtExit *updt );

Activating the report specifications archive definition exit

The report specifications archive definition exit is implemented by a single DLL, ARSUUPDT.
ARSUUPDT is a DLL module that is written in the C programming language. The samples that
are shipped (ARSUUPDT and ARSUUPDC) initialize the ARSUUPDA structure and call the ARSUUPDX
ARS.RSADUPDT exit driver.

The ARSUUPDT DLL invokes module ARSUUPDX. Module ARSUUPDX interfaces with the MVS
Dynamic Exit Facility to perform the following actions:
 Define the logical exit point name: ARS.RSADUPDT
 Route control to a set of exit routines that are associated with MVS and process the
results of their execution

Module ARSUUPDZ is implemented as dynamic exit routine that is associated with MVS. An exit
routine is eligible for execution after it becomes associated with the logical exit point. The
MVS Dynamic Exit Facility provides several methods for performing this association.

Chapter 11. Exits 271

 When the exit routine is assembled and link-edited to a library, it must be associated with the
exit in one of two ways:
 Use the exit statement in the PROGXX parmlib member. For more information about the
PROGXX parmlib member, see z/OS MVS Initialization and Tuning Reference,
SA22-7592.
 Use the SETPROG EXIT operator command. For more information about the SETPROG EXIT
command, see z/OS MVS System Commands, SA22-7627.

Use the following command to activate the exit routine and associate ARSUUPDZ with the logical
exit point name. (The example assumes that ARSUUPDZ is in the link pack area (LPA) or a
LNKLST dataset.)
SETPROG EXIT,ADD,EXITNAME=ARS.RSADUPDT,MODNAME=ARSUUPDZ

Enabling the report specifications archive definition exit

To enable the exit in Content Manager OnDemand, run the ARSLOAD program with the -E
parameter.

Note: The -E parameter must be specified in uppercase.

For more information about the report specifications archive definition exit routines, see
Chapter 40, “Report specifications archive definition exit”, in the Content Manager
OnDemand for z/OS Configuration Guide, SC19-3363.

11.5.4 Table space creation exit

With the Content Manager OnDemand table space creation exit, you can act when Content
Manager OnDemand creates a table space, table, or index tables that are used to store
application index data. The exit is not called for the Content Manager OnDemand system
tables. The table space creation exit is used to modify the way Content Manager OnDemand
creates table spaces, tables, or indexes. For table and index creation, you can alter the SQL
that is used to create the table or index.

You can also use this exit to perform other actions during a table space creation. This exit is
useful if you must change default parameters for the table space, the table, or the indexes.
The changes affect only new creations. Example 11-13 shows the header file of the table
space creation exit.

Example 11-13 Header file for the table space creation exit
/**********************************************************************/
/* TBLSPCRT - table space Create Exit */
/* */
/* To activate the table space creation exit, set the following */
/* variable in the appropriate OnDemand instance ars.cfg file: */
/* */
/* ARS_DB_TABLESPACE_USEREXIT=<absolute_dll_path_name> */
/* */
/* INPUT: appl_grp */
/* tblsp_name */
/* table_name */
/* idx_name */
/* sql (allocated with 16384 bytes) */
/* action */
/* instance */
/* */

272 IBM Content Manager OnDemand Guide

/* OUTPUT: */
/* */
/* 1) OnDemand will invoke the exit with action == 1 */
/* so that the exit can create the table space (tblsp_name) */
/* using (sql) */
/* *created -> 0 exit did not create the table space, */
/* OnDemand needs to create the table space */
/* using (sql), which can be left unchanged */
/* or modified by the exit */
/* *created -> 1 exit created the table space */
/* */
/* 2) OnDemand will then invoke the exit with action == 2 */
/* so that the exit can create the table (table_name) */
/* inside of the table space (tblsp_name) using (sql) */
/* *created -> 0 exit did not create the table, */
/* OnDemand needs to create the table */
/* using (sql), which can be left unchanged */
/* or modified by the exit */
/* *created -> 1 exit created the table */
/* */
/* 3) OnDemand will then invoke the exit with action == 3 */
/* so that the exit can create the table indexes (idx_name) */
/* inside of the table space (tblsp_name) for table */
/* (table_name) using (sql). This will be invoked based */
/* on the number of indexes to create for the appl_grp */
/* *created -> 0 exit did not create the index, */
/* OnDemand needs to create the index */
/* using (sql), which can be left unchanged */
/* or modified by the exit */
/* *created -> 1 exit created the index */
/* */
/* 4) OnDemand will then invoke the exit with action == 4 */
/* so that the exit can perform any additional work */
/* *created -> Is not used */
/* sql -> If sql is not an empty string, OnDemand */
/* will issue (sql) to the database */
/* */
/* If ARS_DB_TABLESPACE_USEREXIT_EXTRA=1 is defined in */
/* ars.cfg, then the following actions will also be invoked */
/* when OnDemand needs to do further actions: */
/* */
/* 5) OnDemand will invoke the exit with action == 5 */
/* so that the exit can drop the table space (tblsp_name) */
/* using (sql) */
/* *created -> 0 exit did not drop the table space, */
/* OnDemand needs to drop the table space */
/* using (sql), which can be left unchanged */
/* or modified by the exit */
/* *created -> 1 exit dropped the table space */
/* */
/* 6) OnDemand will invoke the exit with action == 6 */
/* so that the exit can drop the table (table_name) */
/* using (sql) when OnDemand needs to drop a table */
/* *created -> 0 exit did not drop the table, */
/* OnDemand needs to drop the table */
/* using (sql), which can be left unchanged */
/* or modified by the exit */
/* *created -> 1 exit dropped the table */
/* */
/* 7) OnDemand will invoke the exit with action == 7 */

Chapter 11. Exits 273

 /* so that the exit can drop the index (idx_name) */
/* using (sql) */
/* *created -> 0 exit did not drop the index, */
/* OnDemand needs to drop the index */
/* using (sql), which can be left unchanged */
/* or modified by the exit */
/* *created -> 1 exit dropped the index */
/* */
/* 8) OnDemand will invoke the exit with action == 8 */
/* so that the exit can alter the table (table_name) */
/* using (sql) */
/* *created -> 0 exit did not alter the table, */
/* OnDemand needs to alter the table */
/* using (sql), which can be left unchanged */
/* or modified by the exit */
/* *created -> 1 exit altered the table */
/* */
/* RETURN_CODE: */
/* 0 -> Successful */
/* Otherwise -> Failed */
/* */
/**********************************************************************/
ArcI32
ARSCSXIT_EXPORT
ARSCSXIT_API
TBLSPCRT( ArcCSXitApplGroup *appl_grp,
char *tblsp_name,
char *table_name,
char *idx_name,
char *sql,
ArcI32 action,
ArcI32 *created,
char *instance
);

You can use SQL code to customize the following actions:

 Creating a table space
 Creating a table
 Creating an index
 Other additional action

If you do not customize the action, Content Manager OnDemand uses the defaults.

Example 11-14 shows a sample program flow.

Example 11-14 Sample program flow

Action 1
Is there a need to customize the creation of the table space?
If yes
create the tablespace
return( created = 1)
Else
OnDemand create the tablespace
return( created = 0)

Action 2
Is there a need to customize the creation of the table?
If yes

274 IBM Content Manager OnDemand Guide

 create the table (in the tablespace)
return( created = 1 )
Else
OnDemand create the table
return( created = 0 )

Action 3
Is there a need to customize the creation of the indexes?
If yes
create the indexes
return( created = 1 )
Else
OnDemand create the indexes
return( created = 0 )

Action 4
Final call, is there additional work, clean up or update on parameters?
If yes
perform the additional action.
return( created = not used )
Else
OnDemand do nothing
return( created = not used )

Activating the table space creation exit

The exit is turned on by setting the following parameter in the ARS.CFG file, which is in the
config directory of the Content Manager OnDemand installation root.

The following statement must exist in the ARS.CFG file that is associated with the instance so
that the ARSUTBL DLL can be invoked:
ARS_DB_TABLESPACE_USEREXIT=absolute path name

Where “absolute path name = ... /bin/exits/arsutbl”

For more information about the table space creation exit, see the IBM Content Manager
OnDemand for Multiplatforms - Installation and Configuration Guide, SC18-9232.

11.5.5 ARSYSPIN and sample APKACIF exit on z/OS

The JES Spool Capture facility ARSYSPIN and the sample APKACIF exit are provided on z/OS.
ARSYSPIN provides a means to collect and consolidate the JES spool (SYSOUT) dataset into
one or more files so they can be archived by Content Manager OnDemand. The facility runs
as a started task in its own address space. A control statement file is used to provide
ARSYSPIN parameters. These parameters specify JES Spool file selection criteria (for
example, the sysout class that is taken for Capture output) and other operational
characteristics.

ARSYSPIN creates an intermediate output file that contains one or more spool files from one or
more jobs. The intermediate output file is indexed and stored in Content Manager OnDemand
by using the ARSLOAD program. ARSYSPIN invokes ARSLOAD when sufficient data is captured in
the intermediate output file. ARSLOAD calls the indexer program (APKACIF) to extract the index
values from the data and store them in an index file. ARSLOAD adds these index values to the
database and stores the data object. If you want, you can use ARSYSPIN exits to augment the
data stream.

Chapter 11. Exits 275

 In particular, the ARSYSPIN Input Exit (UX03) and Separator Exit (UX06) provide substantially
more information about the job that produced the spool file that is being processed than what
is available at the time when APKACIF (or another indexer program) is driven by Content
Manager OnDemand. In addition, the processing impact of driving ARSYSPIN exit routines is
lower than the impact that is associated with the indexer exit routines, such as ARSSPVIN.

ARSSPVIN is a sample APKACIF input exit that is provided with ARSYSPIN to introduce additional
index values into the data stream, by using a “trailer” record. Trailer records are inserted at
the end of the JESMSGLG data. They reflect the highest severity condition (a step completion
code, an ABEND code, or another type of problem, such as a JCL error) that is observed in
messages that are contained within these spool files.

Special considerations for APKACIF exits that are written in COBOL

The provided sample exit is written as a COBOL main program. To prevent the IBM Language
Environment® from creating and destroying the COBOL runtime environment each time that
ARSSPVIN is called, a CEEUOPT CSECT must be assembled and link-edited with the COBOL
object code.

Constructing a CEEUOPT CSECT is documented in z/OS Language Environment

Customization, SA22-7564. A sample CEEUOPT CSECT is included in dataset
CEE.SCEESAMP(CEEUOPT). You can use this sample as a model, but you must ensure that
the following option is specified:
RTEREUS=(ON)

CEEUOPT CSECT must be assembled and link-edited with the COBOL object code. In
addition, you must ensure that the resulting module is link-edited as NOT RE-ENTRANT and
NOT REUSEABLE. This task is required for the local variables within the COBOL exit code to
retain their values. This exit is invoked several times during an ACIF run. The sample source
code is in the SARSINST library member ARSSPVIN. Example 11-15 shows a sample
CEEUOPT CSECT.

Example 11-15 CEEUOPT CSECT

CEEUOPT CSECT ,
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
CEEXOPT
ABPERC=(NONE), +
ABTERMENC=(ABEND), +
AIXBLD=(OFF), +
ALL31=(ON), +
ANYHEAP=(16K, 8K, ANYWHERE, FREE) +
BELOWHEAP=(8K, 4K, FREE), +
CBLOPTS=(ON), +
CBLPSHPOP=(ON), +
CBLQDA=(OFF), +
CEEDUMP=(60,SYSOUT=*,FREE=END,SPIN=UNALLOC), +
CHECK=(ON), +
COUNTRY=(US), +
DEBUG=(OFF), +
DEPTHCONDLMT=(10), +
DYNDUMP=(*USERID,NODYNAMIC,TDUMP), +
ENVAR=(’’), +
ERRCOUNT=(0), +
ERRUNIT=(6), +
FILEHIST=(ON), +
FILETAG=(NOATOCVT,NOAUTOTAG), +
HEAP=(32K,32K,ANYWHERE,KEEP,8K,4K), +

276 IBM Content Manager OnDemand Guide

HEAPCHK=(OFF,1,0,0,0), +
HEAPPOOLS=(OFF,8,10,32,10,128,10,156,10,1024,10,2048, +
10,0,10,0,10,0,10,0,10,0,10,0,10), +
INFOMSGFILTER=(OFF,,,,), +
INQPCOPN=(ON), +
INTERRUPT=(OFF), +
LIBSTACK=(4K,4K,FREE), +
MSGFILE=(SYSOUT,FBA,121,0,NOENQ), +
MSGQ=(15), +
NATLANG=(ENU), +
NOAUTOTASK=, +
NOTEST=(ALL,*,PROMPT,INSPPREF), +
NOUSRHDLR=(’’), +
OCSTATUS=(ON), +
PC=(OFF), +
PLITASKCOUNT=(20), +
POSIX=(OFF), +
PROFILE=(OFF,’’), +
PRTUNIT=(6), +
PUNUNIT=(7), +
RDRUNIT=(5), +
RECPAD=(OFF), +
RPTOPTS=(OFF), +
RPTSTG=(OFF), +
RTEREUS=(ON), + <====ATTENTION
SIMVRD=(OFF), +
STACK=(128K,128K,ANYWHERE,KEEP,512K,128K), +
STORAGE=(NONE,NONE,NONE,OK), +
TERMTHDACT=(TRACE,,96), +
THREADHEAP=(4K,4K,ANYWHERE,KEEP), +
THREADSTACK=(OFF,4K,4K,ANYWHERE,KEEP,128K,128K), +
TRACE=(OFF,4KDUMP,LE=0), +
TRAP=(ON,SPIE), +
UPSI=(00000000), +
VCTRSAVE=(OFF), +
XPLINK=(OFF), +
XUFLOW=(AUTO) +
END,

Activating the exit

To activate the exit, you must add the executable file to a loadlib in the Steplib (ARSLOAD)
procedure. You must also supply the ACIF control statement INPEXIT = ARSSPVIN to the
indexing parameters. You can perform this task when you add an application in the Indexer
Information window.

Chapter 11. Exits 277

 Complete the following steps:
1. Open the Add an Application window and click the Indexer Information tab, as shown in
Figure 11-3.

Figure 11-3 Indexer Information tab

2. Click Modify.
3. Click the Exit Information tab, as shown in Figure 11-4.

Figure 11-4 Specify Load Module Name in the Exit Information tab

4. In the Input Records field, enter the name of the exit.

5. Click OK.

The exit is added to your indexing parameters.

278 IBM Content Manager OnDemand Guide

Editing the indexer parameters
Figure 11-5 shows the Edit Indexer Parameters window.

Figure 11-5 Edit exit information

If an application exists, edit your indexing parameters and add the following line, as in shown
in Figure 11-5:
INPEXIT=ARSSPVIN

For more information about activating this exit, see the Content Manager OnDemand for z/OS
Version 9.0 Administration Guide, SC19-3364.

Chapter 11. Exits 279

280 IBM Content Manager OnDemand Guide
 Part 3

Part 3 Advanced system

concepts and design
This part contains the following chapters:
 Chapter 12, “Scalability, reliability, and availability architectures” on page 283
 Chapter 13, “Performance” on page 297

© Copyright IBM Corp. 2003, 2015. All rights reserved. 281

282 IBM Content Manager OnDemand Guide
 12

Chapter 12. Scalability, reliability, and

availability architectures
IBM Content Manager OnDemand (Content Manager OnDemand) is a lightweight process,
that is, the Content Manager OnDemand code itself does not require extensive system
resources to perform the functions that are required of it. Content Manager OnDemand
installations scale to handle both large quantities of data and many users. The total quantity
of data that is stored or retrieved at any time is the main contributor to the resource
consumption on the server. This chapter focuses on the scalability, reliability, and availability
of Content Manager OnDemand systems.

In this chapter, we cover the following topics:

 Scalability, reliability, and availability defined
 Scaling a Content Manager OnDemand system
 High availability

© Copyright IBM Corp. 2003, 2015. All rights reserved. 283

12.1 Scalability, reliability, and availability defined
This section defines scalability, reliability, and availability and how they relate to a Content
Manager OnDemand system.

Scalability
Scalability is the ability of a Content Manager OnDemand system to handle a growing amount
of work with no performance degradation. A Content Manager OnDemand system’s
performance improves with the addition of hardware and network resources and therefore is
defined as a scalable system. Two types of scalability are defined:
 Horizontal scalability (or scale out): This type of scalability is achieved by adding more
nodes, systems, or logical partitions (LPARs) to a Content Manager OnDemand instance.
An example of horizontal scalability is adding more object servers to a Content Manager
OnDemand instance.
 Vertical scalability (or scale up): This type of scalability is achieved by adding more
resources to a single node in a Content Manager OnDemand instance. Typically, this type
of scalability involves faster processors, more processors, memory, disks, or networking
hardware.

Content Manager OnDemand is both horizontally and vertically scalable.

Reliability
Reliability is the ability of Content Manager OnDemand to perform and maintain functionality
during regular workloads and during peak workloads. Peak workloads might occur regularly
(for example, when everyone signs on at 9:00 a.m.) or periodically (at the end of the month
when more processing than usual occurs). Or, peak workloads might occur sporadically (for
example, when a special event occurs, such as a sales drive that results in more users using
the system).

Availability
Availability is a measure of the time that a Content Manager OnDemand server or process
functions normally, and a measure of the time that the recovery process requires after a
component failure. It is the downtime (unavailability) that defines system availability.
Availability is the amount of system uptime when the system is fully functional and accessible
by all users.

Availability requires that the system provides a degree of redundancy to eliminate single
points of failure (SPOFs). The greater the redundancy that is provided, the higher the
availability of the system. A single physical machine is still a SPOF. For this reason, a high
availability system topology typically involves horizontal scaling and redundancy across
multiple machines.

High availability
High availability implies that no human intervention is needed to restore operation if a failure
or outage occurs. A highly available system has an availability limit of at least 99%, which
allows an average of 15 minutes each day to perform maintenance tasks (during which period
the system is inaccessible to users). The degree of high availability that is achieved is a
function of the amount of redundancy within the system and the degree to which this
redundancy is automatically enabled.

284 IBM Content Manager OnDemand Guide

 Basically, two redundancy techniques are available:
 Passive redundancy: This redundancy is achieved by including enough excess capacity in
the design to accommodate a performance decline, such as two Content Manager
OnDemand servers (known as ARSSOCKD on z/OS and Multiplatforms) that access the
same system tables and archive. If one server fails, the other server is available to take on
the workload.
 Active redundancy: This redundancy is used to achieve high availability with no
performance decline. In this case, at least double the required resources are allocated to
the Content Manager OnDemand system. For example, if the peak workload requires 1.5
Content Manager OnDemand servers, three Content Manager OnDemand servers are
configured to work in parallel. If one of the servers fails, the other two servers can take on
the full workload with no performance degradation.

Systems typically become unavailable because of the lack of one or more of the following
activities:
 Change control procedures (a failure to implement the appropriate procedures from
installation verification through performance testing before you place the system into
production)
 Monitoring of production system components (including total system workload, hardware,
and network issues)
 Implementing high availability solutions (redundant systems and network connections)
 A comprehensive backup (and restore) process that is tested on a routine basis

A cost exists to implementing highly available high-performance systems. This cost must be
weighed against the cost of not implementing such systems.

The following sections provide more information about example system implementations that
allow high performance, scalability, reliability, and availability.

12.2 Scaling a Content Manager OnDemand system

A Content Manager OnDemand instance can be scaled from a single system image that
performs all of the required tasks (data loading, library storage, and object storage) to a
multiple system/multiple LPAR configuration, which offers higher levels of performance and
availability. When a Content Manager OnDemand instance is distributed among multiple
systems, these systems might be configured in the following ways:
 Single technology systems: The Content Manager OnDemand instance consists of
systems that are of the same architecture. For example, all systems might be AIX
systems.
 Multiple technology systems: The Content Manager OnDemand instance might consist of
systems of different architectures. For example, the library server and an object server
might be on a z/OS system; two other object servers might be on AIX systems; and
another object server might be on a Microsoft Windows system.

In both of these scenarios, the configuration results in a single Content Manager OnDemand
instance view from both the administrative and user perspectives.

With this flexibility and scalability, you can configure Content Manager OnDemand systems
so that they meet a wide range of both workload and operational requirements.

Chapter 12. Scalability, reliability, and availability architectures 285

 Examples of these configurations are illustrated in the figures in this section. These figures
are only a sample of the possible configurations that are used to illustrate the basic scalability
features.

Figure 12-1 illustrates a single Content Manager OnDemand instance. In this figure, the
Content Manager OnDemand server supports the library server, one or more object servers,
and one or more load processes. The following sections provide examples of how the Content
Manager OnDemand server can be scaled both vertically and horizontally.

Single Sys te m

Libr ary Se rve r

Tmp
Ca che
TC P/IP db2
Network

Obje ct Serve r
Tmp (h fs,zFS)
Ca che
TSM/OAM/VSAM
C lient

Loa d Proce ss
tmp

Figure 12-1 Scalability: A single instance (simple client/server) setup

12.2.1 Vertical scalability

You can scale Content Manager OnDemand vertically by expanding the system, by using a
larger system, through application design, or through parallel archive access.

Expanding the system

Content Manager OnDemand is vertically scalable if the system that it is running on is
scalable. Vertical scalability is achieved by adding more hardware to the system. This
hardware might be in the form of faster processors, more processors, memory, disks, I/O, or
network capacity.

The limit to the amount of possible vertical scalability is the architectural hardware constraints
of the system. For example, if the system supports only 24 GB of memory, that memory
limitation can be overcome only by buying a larger system.

Using a larger system

You can scale a Content Manager OnDemand system vertically by using a larger system in
one of two ways:
 Installing a larger system within the same family and architecture, for example, moving
from an entry-level AIX system to an enterprise-level AIX system
 Installing a larger system from a different architecture and family, for example, moving a
Content Manager OnDemand server from a Windows system to an AIX system

286 IBM Content Manager OnDemand Guide

Application design
Modern computer systems contain multiple cores. They can perform multithreaded
processing. Modern computer system operating systems allow parallelism in operations. To
take advantage of these hardware and software features, an application must be designed so
that it can run in parallel at multiple levels. Content Manager OnDemand can take advantage
of both.

At the process level, the Content Manager OnDemand server runs multiple processes:
 A library server
 One or more object servers
 One or more load jobs
 The expiration process

At the thread level:

 The library server is designed so that it is multithreaded and it can service multiple
incoming data requests on different threads and perform multiple database queries in
parallel.
 The object server is also multithreaded so that multiple users can concurrently retrieve
data from the Content Manager OnDemand archive.

Parallel archive access

When you access the Tivoli Storage Manager or object access method (OAM) archives, a
store or retrieve request is sent to Archive Storage Manager (ASM). ASM then either stores or
retrieves the data and returns the result to the Content Manager OnDemand server. If this
process is conducted in a serial fashion, the archive storage access mechanism becomes a
bottleneck at high transaction rates. To overcome this potential bottleneck, Content Manager
OnDemand implements connection pooling to the storage archives.

Content Manager OnDemand maintains a pool of connections to the archive. When an

archive store or retrieve request is received, an available connection from the pool is selected
to perform the request. This connection allows both faster access to the archive (by
eliminating the start process each time a connection is requested) and for the parallel
execution of the store or retrieve operations.

On IBM i, when you access the ASM archives, connection pooling is not required for store
requests. When a store request is made, ASM opens a connection and keeps it open until the
data store request is complete. In addition, ASM allows the aggregation of objects, sending
fewer objects to storage media than otherwise are sent without aggregation.

On Multiplatforms and z/OS, you can aggregate documents that are loaded from Content
Manager OnDemand Web Enablement Kit (ODWEK) before you store them in the archive.
The document is stored to cache where it is appended to the storage object until the object
reaches 10 MB (defined storage object size), at which point it is migrated to a storage
manager, such as Tivoli Storage Manager. For more information about this topic, see the
following website:
http://www.ibm.com/support/docview.wss?uid=swg21587507

Chapter 12. Scalability, reliability, and availability architectures 287

12.2.2 Horizontal scalability: Library server
Even though Content Manager OnDemand allows a single library server for each instance,
this library server can be scaled horizontally. The library server is scaled horizontally by using
one or both of the following methods:
 The database tables (both the system and the application group) can be placed in different
databases (z/OS) or different table spaces (Multiplatforms and z/OS) at the table level.
Therefore, each of these tables can scale to the maximum practical size that is supported
by the database within the operational constraints of maintenance and performance.
Content Manager OnDemand does not impose a limitation.
 The application group data table design facilitates the following actions:
– You can create as many application groups as you need to support the required data to
be archived.
– Each application group can be segmented into multiple tables where the table
segmentation is based on size.
– Each of these application group data tables can be placed in a separate database
(z/OS) or table space (Multiplatforms and z/OS).

12.2.3 Horizontal scalability: Multiple object servers

For Multiplatforms and z/OS, you can scale a Content Manager OnDemand system
horizontally by using multiple object servers.

In the example that is shown in Figure 12-2, the Content Manager OnDemand system is
horizontally scaled by placing the library server, object servers, and load processes on
multiple systems.

Horizonta l Sca la bility

Use rs (Gui Clie nt, We b Client, A PIs …) Sto red da ta Lo ad job p rocessi ng
distri buted acro ss distri buted acro ss
mul ti ple in dep end ent mul ti ple in dep end ent
ob ject se rvers ob ject se rvers

+ +

Administr ator Lib rary Ob ject Obje ct L oad Load

Server Server Serve r Pro cess Pro cess

OnDem and Ins tance

Figure 12-2 Horizontal scaling: Multiple object servers (z/OS and Multiplatforms)

This form of horizontal scalability provides better performance, reliability, and scalability by
distributing the storage and retrieval workload over multiple systems.

From a Content Manager OnDemand perspective, no limit exists to the number of object and
load process servers. Each of the servers can run to its maximum capacity. Operational
limitations are imposed by the TCP network bandwidth that connects all of the servers and by
the available data center floor space. Both of these constraints can be reduced by placing
multiple servers in a rack-mounted configuration.

288 IBM Content Manager OnDemand Guide

 This example and all of the following examples, from an external perspective, show a single
Content Manager OnDemand instance. The fact that the system consists of multiple
distributed systems is transparent to both of the following groups:
 The Content Manager OnDemand administrator, who continues to administer the system
through the Content Manager OnDemand Administrator Client as though it is a single
physical system.
 The Content Manager OnDemand users, who continue to access the whole system
through a single IP address (that of the library server) and see only a single system from
their perspective.

12.2.4 Horizontal and vertical scalability: Storage manager

This form of horizontal scalability provides better performance, reliability, and scalability by
distributing the storage and retrieval workload over multiple storage subsystems within each
object server.

An object server controls the storage and retrieval of the archived data. The archived data is
stored in a storage subsystem. The number and architecture of these subsystems can be
scaled to the limitations of the subsystem. Each object server can support one or more
storage subsystems, and each storage subsystem can consist of multiple storage devices, as
shown in Figure 12-3.

Use rs (Gui Clie nt, We b Client, APIs… )

+ +

A dministr ator L ibra ry Obj ect Ob ject Lo ad Lo ad

Se rver Se rver Server Proce ss Proce ss

OnD ema nd Insta nc e

Archive sc alability

Storag e subsystems
Ca che, OAM, TSM

Figure 12-3 Horizontal and vertical scaling: Multiple storage managers

Chapter 12. Scalability, reliability, and availability architectures 289

 Each object server can have multiple storage subsystems of different types:
 Cache: The cache storage subsystem is controlled directly by the object server. Data is
written to and read directly from cache. Cache consists of one or more cache file systems.
Each cache file system can be mounted on a different device in its own directory. Each
device can be placed on its own independent I/O interface/channel. Content Manager
OnDemand does not impose a limit on the number of devices.
 IBM Tivoli Storage Manager: Tivoli Storage Manager is an archive storage subsystem.
The Content Manager OnDemand object server sends data to and requests data from
Tivoli Storage Manager. Each Tivoli Storage Manager server can be installed on its own
system (for example, an AIX server). The Content Manager OnDemand object server
allows the connection of multiple Tivoli Storage Manager servers. So, for example, if the
Content Manager OnDemand object server is an AIX system and the data that is
managed by that object server is stored in three Tivoli Storage Manager archives (all of
which are AIX systems), the total processing capacity for that object server is four AIX
systems. Each of the AIX systems can be configured with as many processors, memory,
disks, and I/O as needed, up to its architectural limitation. If more capacity is needed,
more Tivoli Storage Manager servers or object servers can be added.
 Object access method (OAM): OAM is a z/OS archive storage subsystem only. Only one
OAM archive exists for each system. Scalability within the archive is achieved by
increasing the number of storage groups. A z/OS system can grow by increasing the
number of processors, amount of memory, number of disks, and I/O. If more capacity is
needed than can be provided by a single system, z/OS allows multiple systems to be
connected in a Parallel Sysplex. All of these systems then can access the same OAM
subsystem, therefore providing unparalleled scalability, reliability, availability, and
performance.

Both Tivoli Storage Manager and OAM provide hierarchical data management facilities. Data
can be stored on different devices based on the age or predicted frequency of data access.
For example, frequently accessed data might be placed on high-speed disk and infrequently
accessed data might be placed on tape. When the data is requested by a user, the location of
the data is transparent to the user. The only perceived difference from a user perspective is
the response time, which is mainly a factor of the type of device on which the data is stored. In
this example, tape access is slower than disk access.

In summary, better performance is achieved by distributing the storage and retrieval workload
over multiple systems and multiple devices.

12.2.5 Horizontal scalability: Multiple logical partitions and systems

This scenario is similar to the multiple object server scenario where each object server is
running on a separate system. In this case, the library server and one or more object servers
are installed in separate LPARs on one or more physical systems, as shown in Figure 12-4 on
page 291.

290 IBM Content Manager OnDemand Guide

 OnD ema nd Insta nc e

+ +

Li brary Obje ct Ob ject Lo ad Lo ad

Serve r Serve r Se rver Process Proce ss

LPAR LPAR L PAR LPAR LPAR LPAR

1 2 n 1 2 n

Syst em A Syste m B

Figure 12-4 Horizontal and vertical scaling with multiple LPARs

This scenario is in organizations with large systems, such as AIX or z/OS, that are installed
and that have enough available capacity to support the required Content Manager
OnDemand workload. One advantage of this configuration is that you can control the priority
of work and computer resource distribution to each of the LPARs, such as the number of
processors or the processing priority (depending on the computer system/operating system
architecture) that is allocated to each of the LPARs. So, for example, load jobs can be
assigned a low priority during the day when the focus is on data retrieval and a high priority
during the night when the focus is on data loading.

This setup supports horizontal scalability by using multiple technologies as appropriate. The
main constraint is that clients must have access to all systems through TCP/IP.

12.2.6 Multiple server configuration rules

The following general rules apply when you configure multiple Content Manager OnDemand
servers. In all cases, for additional guidance, see the appropriate Content Manager
OnDemand documentation or contact Content Manager OnDemand Lab Services.
 Each Content Manager OnDemand server has its own set of configuration files.
 The parameters in all configuration files must be set so that all of the servers are part of
the same instance.
 The Content Manager OnDemand clients connect to the IP address listening port of the
Content Manager OnDemand server (library server module).
 The documents are retrieved from the various object servers based on the location
information that is returned by the library server. This retrieval is transparent to the client
systems.
 Parallel load processes must have separate temp directories.

Figure 12-5 on page 292 depicts this configuration type.

Chapter 12. Scalability, reliability, and availability architectures 291

 OnD ema nd Insta nc e

LP AR - 1 arssockd
Temporary s torage

ars. cf g ars. ini

odbc DB2

Library Server
ars soc kd

LP AR - 2 ars objd-1
Cache storage
TCP/IP ars 1.c ac he
Ne twork Temporary st orage ars. ini
Client
A rc hive s torage ars1. cfg
Objec t S erver
ars objd
ars objd-n
LPA R - N
Cache storage
ars 2.c ac he
Temporary st orage ars.ini
ars2. cfg
A rc hive s torage
Objec t S erver
ars objd

Figure 12-5 Multiple server configuration

12.3 High availability

The concept of high availability roughly equates to a system and its data being available
(accessible by users) almost all of the time, 24 hours a day, 7 days a week, and 365 days a
year. In actuality, 100% availability is not a cost-effective reality today for most
implementations; rather, it is a goal. The goal is to design and build systems that are highly
available by minimizing both planned and unplanned outages that can be caused by SPOFs.

12.3.1 Redundant systems: All platforms

Various techniques are employed on all platforms to achieve near high availability. These
techniques are based on creating as much redundancy as possible within the system and the
data that the systems include:
 Preventing data loss: Employing various levels of RAID to store the data on disk.
 Duplicating the data: Creating near real-time copies of the data on backup devices that
replace the online devices if the online devices fail.
 Duplicate systems: A duplicate system (hardware, software, and data) is maintained
(either locally or remotely), and when the main system fails, users are automatically
directed to the duplicate system.
 Network redundancy: Creating multiple paths through the network so that if one path (or
router) fails, the network continues to function.

All of these techniques work well and provide various levels of near real-time high availability
based on the degree to which the redundant systems are created and are kept in
active-standby mode.

292 IBM Content Manager OnDemand Guide

12.3.2 Multiple LPAR sysplex: z/OS
The z/OS operating system has a high availability architecture that is built into it. A z/OS
Parallel Sysplex is a tightly coupled cluster of independent z/OS systems that connect
through an Internet Protocol network. A cluster is 2 - 32 independent systems that are locally
or geographically dispersed. Communication between the z/OS systems in the sysplex is
handled through the cross-system Coupling Facility (XCF). A z/OS Parallel Sysplex
implementation provides the highest level of high availability in the industry.

Figure 12-6 illustrates a Content Manager OnDemand implementation of a two-system highly

available z/OS sysplex system.

CMOD Client

z/OS A

Sysplex Distributor (SD) WLM*

Sysplex Distributor Hot Backup

Other
z/OS B z/OS LPARs
z/OS A
z/OS B
OS LS OS
LS
OAMPlex
OAMPlex
XCF
DB2 (Data Sharing) DB2 (Data Sharing)

This could be one LPAR

Or each component could
be in an LPAR LS DB

OAM DB

Shared Data

Figure 12-6 Scalability: Parallel Sysplex/multiple LPARs (z/OS)

Figure 12-6 illustrates an example of a two-system Content Manager OnDemand Parallel

Sysplex implementation. z/OS system A contains a library server and an object server. The
library server and object server can be either combined in a single executable file (most
common z/OS implementation) or separated into two executable files, in which case they are
installed in separate LPARs. z/OS system B shows a multiple LPAR system with a combined
library/object server that is installed in each of the LPARs.

Both of these systems (all LPARs and all instances of the Content Manager OnDemand
server) access a single set of Content Manager OnDemand database tables through DB2
data sharing. They also access a single OAM archive system through an OAMplex. Not
shown in the figure is the access to a single Job Entry Subsystem (JES) spool and a shared
file system (which consists of a set of hierarchical file systems (HFS) or z/OS file systems
(zFS). The term “single” is used to imply that the same set of data is available to all systems
concurrently. Each of these single systems consists of highly redundant components and
therefore do not represent a SPOF.

Chapter 12. Scalability, reliability, and availability architectures 293

 The z/OS Parallel Sysplex technology enables the Content Manager OnDemand servers to
share configuration files, database, JES, HFS, and archive. For performance reasons, all HFS
read/write directories that are used for temporary storage of data are configured as unique to
each Content Manager OnDemand server.

From a client perspective, the “cluster” is a single IP address. Incoming client requests are
received by the sysplex distributor/Workload Manager (WLM). WLM monitors the various
systems in the Parallel Sysplex and selects the appropriate Content Manager OnDemand
server to forward the request to based on the current system workload and availability, so that
the system that is more available (less busy) receives the request.

12.3.3 High availability: IBM i

IBM PowerHA® SystemMirror® for i is the integrated IBM storage-based clustering solution
for high availability and disaster recovery. The data and applications are deployed into storage
pools, which are called independent auxiliary storage pools (IASPs). IASPs can be deployed
by using either internal or external storage. At any time, the nodes in the cluster can switch
roles and become either a primary or backup node. PowerHA SystemMirror can be used for
on-demand role swap operations.

The IBM Power Systems™ Capacity BackUp (CBU) offerings support disaster recovery and
high availability needs. The CBU offerings recognize that true high availability or disaster
recovery solutions require at least two systems. If one system is not available, the other
system takes over. The CBU offering provides flexible and economic options for deploying
business continuity operations.

In a high availability environment on IBM i, you might not want to replicate the following
directories because OnDemand places only temporary data in them, and this data might
occupy a large amount of space:
 Do not replicate the temporary integrated file system (IFS) directories for your instances.
For example, do not replicate /QIBM/UserData/OnDemand/QUSROND/TMP or
/QIBM/UserData/OnDemand/QUSROND/PRTTMP, where QUSROND is your instance name.
 Do not replicate the home directory for the user that is storing data. For example, if
JOHNDOE is the name of the user profile that stores data into Content Manager
OnDemand, do no replicate /home/JOHNDOE.
 Do not replicate the /tmp directory.

12.3.4 Horizontal and vertical scalability summary

You can use the architectural flexibility of Content Manager OnDemand (Figure 12-7 on
page 295) to select the correctly sized system based on your needs. A Content Manager
OnDemand implementation can be scaled both vertically (by using larger and larger systems)
and horizontally (by increasing the number of systems that are part of the Content Manager
OnDemand instance).

294 IBM Content Manager OnDemand Guide

 Architectu ral flexibility
& scalability
Temp
S torage
HFS
Cache zFS (z/OS)
S torage
Vertical
big ger bo x
TCP/IP Library
Horizonta l
Net work Server (1) odbc
DB2 multip le systems
C lien t
Arc hitec tur al
Tem p
multip le serve r p latforms
Storage
HFS Multip le lo cation s
Cache 2 ti er and 3 tie r
zFS ( z/OS)
Storage Multip le cli ent typ es

TCP/IP or Data Stora ge

Objec t S erver(s) Archive St orage Numb er of ca bin ets,
No TCP/IP (1 or more) TS M – OA M - V SAM
Lo ad pro cess Fo lde r, AGs, App lica ti ons

Same o r d iffe rent machi ne/pl atfo rm

T esti ng comp lexity

Figure 12-7 Horizontal and vertical scalability

A Content Manager OnDemand server can scale from a Windows server up to a cluster of
z/OS systems. It is important to initially select an installation that meets the following
requirements:
 Appropriate for your current workload in terms of the following items:
– Performance
– Reliability
– Availability
– Scalability
 Support for your future growth requirements if the following actions are necessary:
– Increase the number of users that access the system
– Increase the quantity of data that is stored in the system
 Change in the types of archived data
 Change in the preprocessing requirements

Chapter 12. Scalability, reliability, and availability architectures 295

296 IBM Content Manager OnDemand Guide
 13

Chapter 13. Performance

In this chapter, we describe the ways in which the various components within IBM Content
Manager OnDemand (Content Manager OnDemand) might be configured or tuned to
enhance performance. In most cases, it is not possible to give specific parameter values;
however, we provide broad concepts and recommendations in areas where tuning for
performance is possible.

In this chapter, we cover the following topics:

 Tuning Content Manager OnDemand to enhance performance
 Data loading performance
 Data retrieval performance
 Performance issues that are based on data type

© Copyright IBM Corp. 2003, 2015. All rights reserved. 297

13.1 Tuning Content Manager OnDemand to enhance
performance
Two components make up performance: throughput and response time:
 Throughput: The number of transactions (Content Manager OnDemand requests) that can
be satisfied for each unit of time. The more transactions that are run for each unit of time,
the higher the throughput. Higher throughput implies that more users can be served
concurrently and more load jobs can be run in parallel. If the throughput values are low,
the system might not be able to support the required number of users.
 Response time: The amount of time it takes to service a single transaction (Content
Manager OnDemand request). Faster response times imply that the users are able to
retrieve their data faster from the archive, which in turn leads to more satisfied users. If the
response time is slow, users are dissatisfied with the system.

A high performance system, such as Content Manager OnDemand, provides both high
throughput and short response times.

The following sections describe the various components of a Content Manager OnDemand
system and its architecture. They provide guidance about the parameters and configurations
that you can change to improve performance.

The ability to separate the object server from the library server offers two main advantages:
 The ability to share workload by dedicating machines to individual tasks
 The ability to reduce the impact of retrieving a large piece of data over a network that is
either slow or overloaded

13.1.1 Content Manager OnDemand configuration

How reports are defined, indexed, and stored within Content Manager OnDemand greatly
influences the speed at which Content Manager OnDemand can retrieve them. Various hints
and tips for the optimum way to define reports within Content Manager OnDemand are
described in Chapter 3, “Administration” on page 45.

13.1.2 System logging

Use Content Manager OnDemand system logging for usage monitoring, charge-back, or
troubleshooting. Because system logging involves writing all of the selected log messages to
disk, you incur an increase in both resource usage and response time. Logging increases
both the amount of the processor that is used and the amount of I/O to disk. For this reason,
select only the types of logging that you want performed for a particular application group.
Depending on your system usage requirements, you might decide to perform any of the
following tasks:
 Turn off all system logging.
 Record a minimal amount of information (only the information that is needed for reporting
functions).
 Record all transactions.
 Record the log information to one or more external files by using the system log exit.
 Turn on system logging only while you troubleshoot the system.
 Turn on system logging once every time period to sample the system usage patterns.

298 IBM Content Manager OnDemand Guide

13.1.3 System management
For effective system management, set the appropriate value for ARS_NUM_DBSRVR and create
the correct file systems for various Content Manager OnDemand components.

ARS_NUM_DBSRVR
The ARS_NUM_DBSRVR parameter is set in the ars.cfg file. This parameter is the maximum
number of threads that are concurrently open between the Content Manager OnDemand
library server and DB2. Typically, this value is set to a number between 4 - 30. This number
must be large enough to support all of the concurrent database requests from all users and
clients and Content Manager OnDemand commands and daemons, such as ARSLOAD, ARSDOC,
ARSDB, ARSMAINT, and ARSADMIN. This number must not exceed the number of DB2 batch
connections (MAXDBATS for z/OS and MAXAPPLS for Multiprocessing (MP)). The number of DB2
batch connections must be greater than the ARS_NUM_DBSRVR, plus all of the other connections
that are required by all DB2 applications that you defined in your DB2 configuration.

For systems that are running several large load jobs in parallel, or for systems with large
numbers of active users, increase this parameter from the default of 4.

File systems on UNIX

During the installation and setup of Content Manager OnDemand, one of the tasks is to
create the file systems that are required to contain the various Content Manager OnDemand
components.

For performance reasons, when the Content Manager OnDemand file systems are created,
the following components must not be on the same physical media:
 Cache file system
 Database file system
 Primary logs file system
 Secondary logs file system
 Load/indexing file system
 Content Manager OnDemand temporary space file system

13.1.4 Storage management

Regardless of the platforms, storage management with Content Manager OnDemand can be
divided into two areas: cache storage that is managed by Content Manager OnDemand and
archive media that is managed by an external product, such as IBM Tivoli Storage Manager,
object access method (OAM), Virtual Storage Access Method (VSAM), or Archive Storage
Manager (ASM).

For effective storage management, one key performance feature of Content Manager
OnDemand is its ability to load data to archive media, while simultaneously retaining a
temporary cached copy of the most recent archived data on fast access media (such as the
hard disk drive (HDD)). Content Manager OnDemand handles the expiration and
management of this cached copy of the data. After a certain predefined period elapses, the
data is removed from cache. The only remaining copy is held on the much slower archive
media that is managed by either Tivoli Storage Manager, OAM, VSAM, or ASM, depending on
the platform.

If performance problems are encountered at the storage manager level, the issue is almost
always related to the inherent qualities of the slower media types (such as optical platters and
tape volumes) or how the archive media manager is configured.

Chapter 13. Performance 299

 Several of the parameters that affect storage management are ARS_NUM_OAMSRVR,
ARS_NUM_OAMSRVR_SLOW_RETRIEVE, and ARS_OAM_SLOW_RETRIEVE_THRESHOLD.

ARS_NUM_OAMSRVR
This parameter specifies the maximum number of concurrently attached threads between the
Content Manager OnDemand object server and OAM for z/OS. Typically, this value is set to a
number between 4 - 30, depending on client access patterns and object storage locations
(disk versus tape). This parameter has a maximum value of 30. Any value larger than 30
result in a U0039 abend.

ARS_NUM_OAMSRVR_SLOW_RETRIEVE
This parameter determines the number of task control blocks (TCBs) that the Content
Manager OnDemand server starts to handle connections to OAM for retrievals from objects
with a slow retrieval time as defined by the ARS_OAM_SLOW_RETRIEVE_THRESHOLD parameter.
The ARS_NUM_OAMSRVR_SLOW_RETRIEVE parameter applies to all object servers. If the value that
is specified for this parameter is zero (0), no TCBs are dedicated for slow retrievals. All
retrievals are processed by the TCBs that are associated with the ARS_NUM_OAMSRVR
parameter. The default is zero (0). The ARS_NUM_OAMSRVR_SLOW_RETRIEVE TCBs are in addition
to the ARS_NUM_OAMSRVR TCBs, and they use additional DB2 connections.

ARS_OAM_SLOW_RETRIEVE_THRESHOLD
This parameter specifies the threshold at which OAM retrievals are processed by the TCBs
that are associated with the ARS_NUM_OAMSRVR_SLOW_RETRIEVE parameter. If the estimated
retrieval time for an object (as indicated by QELQERRT) is greater than or equal to the value
of the ARS_OAM_SLOW_RETRIEVE_THRESHOLD parameter, the OSREQ RETRIEVE is processed
by an ARS_NUM_OAMSRVR_SLOW_RETRIEVE TCB. The default value is 12000. For other valid
QELQERRT values, see the Object Access Method Application Programmer’s Reference,
SC35-0425-08. An ARS_OAM_SLOW_RETRIEVE_THRESHOLD value of zero (0) with a nonzero
ARS_NUM_OAMSRVR_SLOW_RETRIEVE value causes all OAM retrieve requests to be processed by
the ARS_NUM_OAMSRVR_SLOW_RETRIEVE TCBs, while the ARS_NUM_OAMSRVR TCBs process store,
query, and delete requests.

13.2 Data loading performance

The data loading process is illustrated in Figure 13-1 on page 301. The process begins with
the Content Manager OnDemand Administrator Client defining the application group and
application parameters for the reports to be loaded. These parameters are stored in the
Content Manager OnDemand system tables on the library server.

300 IBM Content Manager OnDemand Guide

Figure 13-1 Data loading

During the load process, in addition to any command-line parameters that are supplied, the
application group and application parameters are retrieved from the library server. Then,
based on the parameter definitions, the load process completes the following steps:
1. Selects the indexer to be used for indexing the report data and retrieves the indexing
parameters.
2. Reads in the report data from the identified source location. The input report data can be
of any data type.
3. Indexes the report data based on the defined indexing parameters.
4. Segments the report into “documents”.
5. Compresses the documents.
6. Stores the compressed documents in storage objects (10 MB by default).
7. Sends the storage objects to the object server where they are stored in the identified
archive (storage node).
8. Sends the index data for the stored objects to the library server where the indexes are
stored in the appropriate application group data table.

13.2.1 Factors that affect the load performance

Many factors affect load performance:
 Quantity, speed, and capacity of the available hardware (processors, memory, disks, I/O
channels, network, and so on)
 Network bandwidth and throughput
 Operating system tuning components: DB2, TCP/IP, and Language Environment

Chapter 13. Performance 301

  Content Manager OnDemand tunable components
 Storage management tunable components: UNIX System Services, z/OS file system
(zFS), hierarchical file system (HFS), OAM, Tivoli Storage Manager, and ASM
 Data components:
– Report file size, document file size (or in the case of large objects, report segment
size), and number of documents per report.
– Number and distribution of triggers, fields, and indexes per document.
– Data type and required data conversion (if any).
– Resource collection for AFP and Portable Document Format (PDF).
– Document compressibility, which is a function of document data complexity and data
type. Text (such as Line Data or SCS) is typically more compressible than AFP, which is
typically more compressible than PDF.
– Storage object size (10 MB default): Contains 100 KB compressed object, which
contains a compressed document.
– Exit routines/programs.

13.2.2 Recommendations
For the most optimal performance in loading, we recommend the following practices:
 For Multiplatforms and z/OS, run parallel load jobs to take advantage of multiprocessors,
large memory pools, multiple data paths, and multiple disk drives.
 Ensure that each parallel load is loading to a different application group.
 Ensure that you set up a different temp directory for each of the parallel loads. The -c
indexDir indexer parameter (which specifies the directory in which the indexer stores
temporary data) must always be specified for ARSLOAD and must be unique for each
running ARSLOAD process.
 For IBM i, start multiple output queue monitors over a single output queue to improve
throughput and take advantage of multiprocessors, large memory pools, and multiple disk
drives.
 Each Content Manager OnDemand process is limited by the performance of a single
processor. For example, the OS/400 indexer uses only one processor when it indexes a
document. Using two or more processors in your system or LPAR does not improve the
performance of the OS/400 indexer. However, by using two or more processors in your
system or LPAR, you might be able to run multiple load jobs simultaneously. You can start
multiple output queue monitors over a single output queue to improve document load
performance.
 For IBM i, the use of the Merge Spooled Files (MRGSPLFOND) command can provide
significant performance improvements when you load SCS spooled files.

302 IBM Content Manager OnDemand Guide

  For IBM i, depending on your retrieval patterns and system hardware configuration, it
might be advantageous to not store a duplicate set of documents in the Content Manager
OnDemand cache when you use ASM because ASM might already be using disk space. If
the application group uses ASM, caches the data, and specifies the migration of data at
load time, two copies of the data are stored during the load. One copy is stored in cache,
and one copy is stored in the ASMREQUEST directory.
To avoid storing a duplicate set of documents in cache for non-AFP data, change Cache
Data to No on the Storage Management tab of your application group definition. To avoid
storing a duplicate set of documents in cache for AFP data, you might change Document
Data to No Cache but leave Resource Data in cache for faster retrieval.
 For IBM i, every user that loads data must have a home directory. If users do not have a
home directory, the temporary files are stored in the root directory of the integrated file
system (IFS).
 If the data source is on a remote system, you can load the data into Content Manager
OnDemand on the remote system and directly store the export data to the specified
Content Manager OnDemand library and object server.
Or, if the data source is on a remote system, you also can upload the data to the specified
Content Manager OnDemand server through FTP and then load the data on the selected
Content Manager OnDemand system.
 For Multiplatforms and z/OS, all file systems must be dedicated file systems that are
mounted on their own mount points.
 For z/OS, when you load PDF reports (by using the PDF Indexer), placing the input report
in the HFS or zFS causes the load to run nearly 50 times faster that compared to the input
report that is placed in a VSAM file.

13.2.3 Load testing

The goal of load testing is to verify that, under stressful system conditions, the required
amount of data can be loaded into the Content Manager OnDemand system within a time
window.

A general approach to load testing a system is described:

 Parallel loads: Run a single load and measure the load throughput. If the throughput does
not meet the requirements, run two loads in parallel and measure the throughput. While
the loads are run, collect system statistics to determine the system resources that are
being used and any potential bottlenecks. Tune or acquire additional system resources as
needed. Progressively increase the number of parallel loads until the required throughput
is met.

Note: For most users, a single load process meets the ingestion throughput
requirements.

 Data types and exits: A different data type, and whether an exit is started during the load
process, affects the load throughput. Test samples of the different types that represent the
general loads.

Chapter 13. Performance 303

13.3 Data retrieval performance
All Content Manager OnDemand clients (such as the Windows client, CICS client, IBM
Content Navigator, ODWEK application programming interfaces (APIs), and structured APIs)
retrieve data from the Content Manager OnDemand server by using a standard proprietary
Content Manager OnDemand protocol. From a Content Manager OnDemand server
perspective, no difference exists between one client and another client.

13.3.1 Data retrieval parameters

Various parameters affect data retrieval performance.

Folder parameters: General tab

In the Content Manager OnDemand Administrator Client, under the Folder parameter and on
the General tab, the following option is available:
 Note Search: If the Annotation flags in a document database are set to No in the Advanced
tab of the General window of the Application Group, this option determines when Content
Manager OnDemand searches the database for annotations and notifies users that
annotations exist for the documents that match a query. Content Manager OnDemand
provides three search and notification methods:
– Hit List: Content Manager OnDemand searches for annotations when the user runs a
query. When annotations exist for a document, the client programs display a note icon
next to it in the document list. This method has a direct performance impact on the
generation of the document list.
– Retrieve: Content Manager OnDemand searches for annotations when the user
selects a document for viewing. This method is the default and recommended value.
– Note: Content Manager OnDemand searches for annotations when the user chooses
the Note option while the user views a document.

Folder parameters: Permissions tab

In the Content Manager OnDemand Administrator Client, under Folder parameters and on
the Permission tab, the following option is available:
 Max Hits: Determines the maximum number of hits that are retrieved and transmitted to
the client. By reducing the maximum number of hits, users are forced to enter queries that
better match the documents that they are searching for. By reducing the maximum number
of hits, the system resources are used optimally both in performing the queries and in
downloading the resulting document list.

TCP/IP considerations
A known Windows configuration setting might affect performance when you connect to a
Content Manager OnDemand server. During repeated searches and retrievals on a Content
Manager OnDemand server, many Windows sockets are opened and closed. Two default
Windows settings might affect heavy traffic between the client and the Content Manager
OnDemand server:
 When an application closes a Windows socket, Windows places the socket’s port into
TIME_WAIT status for 240 seconds; during this time, the port cannot be reused.
 Windows limits the number of ports that an application can use to 5000.

304 IBM Content Manager OnDemand Guide

 To avoid the problems that might result, change the values for the timeout wait time and
number of ports by editing the Windows registry:
 Change the value of the timeout wait time from 240 seconds to a lower number (valid
values are 30 - 300 seconds). The key’s name is shown:
HKEY_Local_Machine\System\CurrentControlSet\services\Tcpip\Parameters\TcpTimedWaitDelay
 Increase the maximum port number from its default of 5000 to a higher number (valid
values are 5000 - 65534). The key’s name is shown:
HKEY_Local_Machine\System\CurrentControlSet\services\Tcpip\Parameters\MaxUserPort

For more information about TcpTimedWaitDelay and MaxUserPort, see your Windows
documentation.

Verify with your network personnel that you are setting the values that are appropriate for your
environment correctly.

13.3.2 Factors that affect retrieval performance

Figure 13-2 shows the data retrieval performance testing, which is an illustration of the
methodology that is used by the Content Manager OnDemand lab for its internal performance
testing. On the client side (where the cTest program is), both throughput and response time
are recorded. The definitions for throughput and response time are shown:
 Throughput: The amount of work that is performed over a period of time (How many
transactions can the Content Manager OnDemand server (CMOD SERVER in the figure)
run at the same time?)
 Response time: The time that is elapsed between when a request is submitted and when
the response from that request is returned (How long does it take for a transaction to run?)

Maximizing performance is a balancing act between optimizing throughput (which is based on

keeping the computing resources busy) and optimizing response times (which requires the
computing resources to be available when they are needed). As the throughput increases, so
does the response time.

Performance Tuning

Same or different system ( z/OS, zLinux, AIX, IBM i, Windows)

cTest CMOD SERVER

(Java client) Induce load (Arssockd)

What is happening Why is it happening

cTest output Tools: SMF, Omegamon
Strobe, db2pm
(Platform independent) responses topas, iostat, vmstat
Transaction perfmon, netstat
Throughput
Averages Response time
Details Analysis: number of Apps,
Ags, folders.. Number of
users, resource availability,
which DASD is the data on

Figure 13-2 Data retrieval performance testing

The concepts that are shown in Figure 13-2 are described for your reference.

The retrieval performance is mostly limited by the resources that are available to the Content
Manager OnDemand server.

Chapter 13. Performance 305

 For example, for disk and I/O capacity, each retrieve requires that the data is obtained from
the archive (Tivoli Storage Manager, OAM, ASM, and cache). This data is on a disk or
another storage device. The storage device retrieval rate is part of the total response time that
is observed at the client, and both of them are affected by the following resources and system
demand:
 Real memory: The data that is retrieved from disk must be stored in memory for it to be
processed. Virtual memory allows large amounts of data to be swapped in and out of real
memory, but it does not remove the need for real memory.
 Processing: Any data transformations that are performed on the Content Manager
OnDemand server require available processing capability. If the capability is not available,
the server waits until it becomes available. This wait lengthens the total response time of
the client request.
 Concurrent retrievals: Each retrieval requires resources on the server. The higher the
number of concurrent retrievals, the greater the amount of resources that are needed to
complete the work in an acceptable amount of time.
 Network bandwidth: The retrieved data is sent to the clients over the Internet Protocol
network. If the network bandwidth is not wide enough to satisfy all of the concurrent
requests, the response time to the clients is slower and data is queued up in the server
buffers, further slowing down the system.

13.3.3 Retrieval testing

The goal of retrieval testing is to verify that, under stressful system conditions, the maximum
number of concurrent users can be served while at the same time the system meets the
business requirements. The following process is a good general approach to retrieval testing
of the system:
 Transaction type: Different types of transactions present different types of workloads on
the system. For example, logon, document query, and document retrieval all use different
components of the Content Manager OnDemand system. For each transaction type,
measure the throughput and response time for a number of concurrent users that exceed
the maximum predicted number. Tune and add resources to the system as needed until
the system exceeds the service level agreement (SLA) requirements.
 Data types: The stored documents might be different sizes and data types (and might
invoke preview exits). Multiple document retrieval tests must be run to verify the
performance for the various types of stored documents.
 User workloads: The users that access the system might all exhibit the same usage
patterns or might exhibit two or more usage patterns. The following process shows an
example usage pattern:
a. Log on.
b. Wait five seconds.
c. Issue a document query with a maximum hit list size of 12 documents.
d. Wait five seconds.
e. Retrieve a 10 KB document.
f. Wait 40 seconds.
g. Retrieve a 20 KB document.
h. Wait 60 seconds.
i. Log off.
For example, a total of 50 concurrent users might follow this pattern. Also, other patterns
might run at the same time. So, the user workload test must model this behavior and it
must also be able to meet the business requirements at peak loads.

306 IBM Content Manager OnDemand Guide

  Test driver location: The code that generates the retrieval workload can be installed on
either of the following machines:
– The same server on which the Content Manager OnDemand system is installed.
By using the same server, you can maximize the stress on the Content Manager
OnDemand system by eliminating the network connection and by using system
processing cycles to generate and measure the response time and throughput.
– A network-connected workstation.
This situation simulates either a web server that connects to the Content Manager
OnDemand server or a user that connects to the Content Manager OnDemand server.
 Number of test drivers: The number of systems that issue the requests can be increased
so that the number of concurrent requests that reach the Content Manager OnDemand
server exceeds the maximum expected number of requests.
 Test measurement: Two sets of measurements are used. The first set is at the test driver,
which represents the user or Content Manager OnDemand Client. At this location, both
throughput and response time on a transaction basis need to be collected. Also, it is
important to check that the system that issues the retrieve requests is not overloaded and
therefore not the performance bottleneck. In addition, at the Content Manager OnDemand
server, request service times can be observed in the Content Manager OnDemand
system log. System performance measurements must be collected by using operating
system-specific tools.

13.3.4 System testing

After the load and retrieval tests are performed individually, it is important to perform an
overall system test. This test must include running everything in parallel up to the maximum
expected system usage. Everything includes load, retrieval, expiration, migration, duplication,
and backup operations. The goal is to ensure that under the most stressful conditions
possible, the system meets business requirements.

Note:
 The performance tuning process demands great skill, knowledge, and experience, and
it cannot be performed by only analyzing statistics, graphs, and figures.
 The goal is to tune the Content Manager OnDemand server. You can “see” the
bottlenecks in the server only if both the client and the network are clear of bottlenecks.

13.4 Performance issues that are based on data type

This section describes issues that relate to individual data types that can significantly affect
the overall performance of Content Manager OnDemand. Several issues can be addressed
by selecting or clearing certain functions and features within Content Manager OnDemand.
Several of the issues that we describe can be addressed only by changing the way in which
the data is produced from the source.

Chapter 13. Performance 307

13.4.1 PDF data
Portable Document Format (PDF) data is an increasingly common data type that can be
archived within Content Manager OnDemand. The following key advantages are available by
using this data type as a document format:
 It is a read-only format that does not require any external resources, such as images or
fonts. It is self-contained.
 The viewer for PDF can be downloaded at no charge from the Adobe website and the
browser plug-ins for PDF are also available at no charge.

During PDF document creation, resources, such as images and custom fonts, are placed in
the data stream once and then referenced many times from within the PDF file. If a large
report is produced from many small documents, that report requires only one copy of the
resources.

However, when the PDF is indexed, the PDF Indexer creates many PDF documents from the
input file. Each of these documents requires a certain number of PDF structures, which define
a document. These documents are concatenated together in the .out file, and then loaded
into Content Manager OnDemand as separate documents. Because the resources are
extracted and placed into a separate resource file, they are not included in each document.
For an illustration of the process, see Figure 13-3.

Document
Resources

Converted to
One PDF file
with
documents
and resources

Many
separate PDF
documents
with resources
removed in
the .out file

Figure 13-3 PDF indexing

If no resources are collected, the size of the .out file, which contains all of the individual
documents, might be larger than the original file. For tips about how to reduce the size of the
output file, see 7.3.5, “PDF indexing: Using internal indexes (Page Piece Dictionary)” on
page 173.

308 IBM Content Manager OnDemand Guide

 The size of the input file and the output file can create problems during the load process:
 The temporary space that is used during indexing can be too small and the load fails.
 The maximum input file size that the PDF Indexer can process is 4 GB, but the
recommended maximum size for a single document (after indexing) is 50 MB. If this size is
exceeded, the system might run out of disk space or memory.

Create PDF data with the base 14 fonts, which do not need to be included in the PDF file.
Because they are not included in the PDF file, they are not extracted during resource
collection, which improves performance. For more information about the PDF data stream
and fonts, see 7.3.1, “PDF fonts and output file size” on page 166.

13.4.2 Line data

Line data (ASCII or EBCDIC text-based reports) is the most common type of data that is
stored in Content Manager OnDemand. The type of line data that we describe here is a
special form of transaction-style report, where it is necessary to search on a value that
appears on every line of the report. This transaction data has a transaction number that
appears on every line and must be sorted either by column or row and either ascending or
descending.

When you index transaction data, if each transaction number from each line of the report is
treated as a database index, such as date or customer name, the database becomes large
quickly. Content Manager OnDemand has a special type of field for transaction data, which is
illustrated in Figure 13-4 by the boxed data on the left of the window.

Figure 13-4 Transaction data in graphical indexer

The transaction data field selects the first and last values from a group of pages and only
these group level values are inserted into the database. Content Manager OnDemand
queries the database by comparing the search value that is entered by the user to two
database fields, the beginning value and the ending value. If the value that is entered by the
user falls within the range of both database fields, Content Manager OnDemand adds the
item to the document list.

Chapter 13. Performance 309

 From a performance perspective, the use of the transaction data field for transaction-style line
data optimizes indexing performance by reducing the number of index values to be inserted
into the database. Therefore, the process of loading and retrieving these large reports is
faster and the Content Manager OnDemand database is many times smaller.

13.4.3 AFP data

AFP data is a multi-part data type. In addition to the variable data, external resources, such
as images, fonts, and logos, are also referenced by the AFP data stream. When Content
Manager OnDemand stores AFP data, the resources are also archived. When the data is
viewed, the referenced resources are displayed.

It is a common misconception that if fonts are collected when the data is loaded, they are
available for viewing in the Windows client. However, Windows does not recognize AFP fonts.
It is not possible to use these fonts even if they are sent to the client as part of the resource.
Windows clients require a mapping from AFP fonts to Adobe Type Manager (ATM) fonts or
TrueType (TT) fonts. Content Manager OnDemand provides this mapping for most standard
fonts. For more information about mapping custom fonts, see IBM Content Manager -
Windows Client Customization Guide and Reference, SC27-0837.

One possibly useful implementation of storing fonts with the resource group is when server
reprint is necessary. If the fonts are stored with the resource group, they can be retrieved from
Content Manager OnDemand and used by AFP printers. However, if fonts are collected, they
are also sent to the client as part of the resources group and then discarded. Storing the fonts
with the resource group serves only to increase network traffic when transferring the resource
to the workstation. A more practical option for server printing is to store the font in a fontlib
and to keep only the reference (path) to the fontlib. Although the font is accessible on the
server, Print Services Facility (PSF) or InfoPrint does not need the font to be inline (stored in
the resource group). The use of this approach also allows all AFP data that references the
font to use the single instance of the font without redundant inline storage.

Figure 13-5 on page 311 shows the indexer information in the application where you can
select the resources to collect with the Restype= parameter. Unless reprints to AFP printers
with 100% fidelity is a requirement, do not collect the fonts.

310 IBM Content Manager OnDemand Guide

Figure 13-5 Collecting AFP fonts

The Content Manager OnDemand for i server does not collect the fonts and it does not give
the administrator that option. The Resource Information window (under Indexer Properties) is
not available to the Content Manager OnDemand for i administrator. If you are reprinting to an
AFP printer, the fonts must be available on the IBM i server, or font substitution is performed.

Chapter 13. Performance 311

13.4.4 Image data
To optimize performance with storing and retrieving image formats, such as Tagged Image
File Format (TIFF), Graphics Interchange Format (GIF), and Joint Photographic Experts
Group (JPEG), do not compress the data because the file sizes might increase. To turn off
compression, select the Disable option from the Load Information tab within the application.
See Figure 13-6.

Figure 13-6 Disabling compression

Two methods are available to turn off data compression:

 Disable: Content Manager OnDemand does not compress the input data. Choose this
option when the input data, such as PDF and compressed TIFFs, is already compressed.
Documents are extracted by the appropriate viewer on the client (for example, Adobe
Acrobat Reader).
 None: Content Manager OnDemand does not compress the input data when it loads the
input data into the system. When the user selects a document for viewing, Content
Manager OnDemand compresses the document before it transmits it over the network and
extracts the document at the client.

312 IBM Content Manager OnDemand Guide

 Part 4

Part 4 Enhancement options

This part contains the following chapters:
 Chapter 14, “Report distribution” on page 315
 Chapter 15, “Full text search” on page 335
 Chapter 16, “Enhanced Retention Management” on page 353
 Chapter 17, “Content Federation Services for Content Manager OnDemand and IBM
Enterprise Records” on page 365

© Copyright IBM Corp. 2003, 2015. All rights reserved. 313

314 IBM Content Manager OnDemand Guide
 14

Chapter 14. Report distribution

IBM Content Manager OnDemand Distribution Facility (ODF) is an optional report distribution
feature for IBM Content Manager OnDemand. ODF provides an easy way to automatically
group reports and portions of reports and distribute the reports to multiple users. ODF
distributions can be printed, created as an output file, or emailed as an attachment.

ODF can distribute reports that are stored in a Content Manager OnDemand server on any
platform that is supported by Content Manager OnDemand.

In this chapter, we cover the following topics:

 Introduction to Content Manager OnDemand Distribution Facility
 Defining the objects with the Administrator Client
 Defining the objects by using batch administration
 Customizable user exits
 Status and monitor tool

© Copyright IBM Corp. 2003, 2015. All rights reserved. 315

14.1 Introduction to Content Manager OnDemand Distribution
Facility
Before Content Manager OnDemand version 9.5, two report distribution components were
available:
 OnDemand Distribution Facility for z/OS
 Report Distribution Facility for Content Manager OnDemand for Multiplatforms

Both of these components contained certain strengths and weaknesses. In V9.5, the
strengths of both of these components were merged into a single component named
OnDemand Distribution Facility (ODF), which offered the following advantages:
 It runs on all Content Manager OnDemand platforms.
 It can run on a separate platform from where the Content Manager OnDemand server is
installed.
 Its operation can be monitored through a new graphical monitor, the OnDemand Monitor.
 It includes transform support where Content Manager OnDemand can transform content
from one data type to another data type before the content is sent as part of an ODF
distribution.

This chapter describes ODF V9.5. For any new installations (on z/OS or AIX) before version
9.5 of Content Manager OnDemand, we suggest that you install ODF.

Figure 14-1 shows the evolution and merger of ODF 9.5 from its predecessors ODF9.0 and
Report Distribution System (RDF) 9.0.

Figure 14-1 Evolution of ODF

When you load documents into Content Manager OnDemand, you might need to print these
documents or send them to various people in your organization.

Content Manager OnDemand automates the process of sending the documents that are
loaded into Content Manager OnDemand to print (or the JES spool), a file (or a z/OS
dataset), to a recipient as an email attachment, or to a recipient as an email notification.

316 IBM Content Manager OnDemand Guide

Another benefit to using ODF is that you can select and combine documents from different
reports and organize them by defining their order and separating them by using banner
pages.

Figure 14-2 is an overview of the OnDemand Distribution Facility and its interaction with the
Content Manager OnDemand server.

Figure 14-2 Content Manager OnDemand Distribution Facility overview

Figure 14-2 shows that the Content Manager OnDemand server and its operation did not
change. Reports and documents are loaded into the server, and system users continue to
view and print their documents normally. The only addition to the library server is a set of ODF
tables that define the documents that are to be distributed to which users and when. The ODF
process reads the ODF tables and collects the required documents and bundles them for
each recipient. ODF then send out the “bundles” to the appropriate destinations (email, file,
and print). Alternatively, ODF can send each recipient (based on system definitions) an email
notification that the report and document were loaded and are available for viewing.

Different organizations have different report and document load and retrieval patterns. In
certain cases, documents are loaded and never retrieved. In other cases, a loaded document
is retrieved multiple times by multiple users. In other cases, it is known that when a specific
report or document is loaded, one or more copies must be distributed to one or more
destinations. What benefit does automating this distribution process provide?

The biggest benefit is that as reports are loaded into Content Manager OnDemand regularly,
they can be delivered automatically to one or more users as they are loaded. Also, after the
distribution is set up, no other changes are required, such as changing the document
selection criteria to identify the latest data that is loaded.

For example, suppose that your organization generates monthly statements for your
customers. You must store these documents in Content Manager OnDemand, and you must
print the statements and mail them to the customers. With ODF, you can set up a distribution
that automatically retrieves these documents as they are loaded into Content Manager
OnDemand and sends them to a spool file for printing.

Chapter 14. Report distribution 317

 Another example is a sales team that generates a monthly sales report for each person on
the sales team. The sales manager needs a copy of these reports. A distribution can be set
up to email the documents to the appropriate sales manager.

The applications for using ODF are endless, but the basis for using it is the same. Documents
are loaded regularly and are needed by one or more users as they become available in
Content Manager OnDemand. Let us look at a specific example from our fictitious company
that was introduced in 1.2.1, “Background information of an example company” on page 6.

AFinancial Co generates monthly credit card statements for all its customers. These
customers can choose to receive a hardcopy of the statement or have the statement sent to
them as an email attachment.

In this example, even though separate customer statements are created each month, they are
loaded into the system at the same time, so only one load occurs each month. This
information is important when you are determining the best way to set up the distribution.
Before a distribution is set up, ask yourself the following questions:
 What documents are needed?
 Who receives the documents?
 When are the documents retrieved and delivered?
 Where are they delivered?

14.1.1 What documents are needed

In our example, we identified our documents as the customer statements. How do you identify
the customer report that you need from the hundreds of thousands of documents that are
stored in Content Manager OnDemand? Certain customers might receive multiple monthly
statements.

In general, you identify the documents by creating an SQL query that uses index fields and
values that uniquely identify the documents that you want to retrieve when they are loaded.
You can then define the distribution to include multiple report bundles with different SQL
queries for each bundle. If the SQL must retrieve the document that is the same except for a
value that identifies the recipient, a single distribution can be used with a recipient list. In this
case, the SQL specifies a wildcard value. When processing, ODF fills in the recipient ID in the
SQL statement. For example, a recipient list contains recipients 100001, 100002, and 100003
and an SQL statement of “Where branch_id = '$ODF_RECIPIENT'”. When this recipient list is
processed, ODF creates a distribution for recipient 100001 with all reports where branch_id =
'100001', recipient 100002 will receive a distribution that contains all reports where branch_id
= '100002', and so on.

14.1.2 Who receives the documents

In our example, each customer needs a statement copy every month. To identify the
customers to Content Manager OnDemand, an ODF recipient must be created for each
customer. Depending on how the documents are delivered, a destination must be set up. For
example, if a set of documents will be delivered to a recipient by using email, an email
address must be specified in the recipient definition.

14.1.3 When the documents are retrieved and delivered

ODF operates throughout the 24-hour day. You can schedule your distributions to be
processed at a specific time of day or processed as they are loaded. To specify when the
distribution is delivered, choose the method, which is either Loaded, All Ready, Time of Day,
Time of Print, or external.

318 IBM Content Manager OnDemand Guide

 ODF operates on a 24-hour clock: 00:00 to 23:59. If a time of distribution (TOD) of 01:00 is
specified and documents are loaded at 23:30, the documents are processed immediately and
they do not wait until the next day because the TOD specified was reached for that 24-hour
day.

14.1.4 Where are they delivered

You can deliver the distribution to a printer (or the JES spool on z/OS) for printing, a file (or
TSO dataset on z/OS), or an email attachment. Alternatively, you can specify that the
documents will not be distributed at all and that an email notification that the documents were
loaded is sent to the specified recipients. In our example, certain customers specified that
they want their statements to be delivered by email, and other customers specified that they
want a hardcopy.

14.1.5 Cross-platform access

ODF (running on any supported platform) can access a Content Manager OnDemand
instance that is running on any (local or remote) platform that is supported by Content
Manager OnDemand. For more information about how to configure ODF, see “Configuring
ODF” in the OnDemand Distribution Facility Installation and Reference Guide, SC19-3358.

14.2 Defining the objects with the Administrator Client

After you set up the Content Manager OnDemand (application group and application) objects,
you are ready to set up the ODF objects. This section describes the definition of the ODF
objects by using the Content Manager OnDemand Administrator Client (Figure 14-3).

Figure 14-3 Administrator Client ODF objects

Chapter 14. Report distribution 319

14.2.1 Adding a recipient
The recipient object contains all of the information about the recipient of the distribution. The
only required field is the recipient ID, which, when combined with the distribution name,
uniquely identifies the distribution.

Figure 14-4 shows the window where you add a recipient.

Figure 14-4 Add a Recipient

Recipients who receive a printed copy of the distribution can choose to include a banner page
in the distribution by selecting Use Banner Page. You can specify up to eight header lines to
include in the banner page, as shown in Figure 14-5 on page 321.

320 IBM Content Manager OnDemand Guide

 Figure 14-5 Specifying banner page information

14.2.2 Adding a recipient list

If several recipients must receive the same reports at the same time, you can create a
recipient list. With this list, you create a single distribution that is sent to every recipient in the
list.

Recipients are added to the list by selecting the ID on the left and clicking Add, as shown in
Figure 14-6 on page 322.

Chapter 14. Report distribution 321

 Figure 14-6 Adding a recipient list

14.2.3 Adding a report ID

The next step is to define the reports to ODF. The report ID identifies the application group
and application to which the report belongs. Figure 14-7 shows the window where you add
the report ID.

Figure 14-7 Adding a report ID

To create a report ID, specify the identifier and then choose the application group and
application from the drop-down selection.

322 IBM Content Manager OnDemand Guide

 Use the reference field to control when a report is available for distribution. The value that you
enter in this field is used with a marked index column in the Content Manager OnDemand
application group. When a reference value is available, the reference value is matched with
the index value of the report. If a match exists, the report is made available for distribution.
This tool is useful if several drafts of a report exist and you want to distribute only the final
version.

14.2.4 Adding a distribution

Now that the recipients and report IDs are set up, it is time to create the distributions. In the
distribution definition, you specify when, where, and how the distribution is delivered. In our
example, we create a distribution that is processed while the documents are loaded. The
output is sent as an email. For a sample distribution definition, see Figure 14-8.

Figure 14-8 Adding a distribution

Distribution Name
With the recipient or recipient list name, the distribution name uniquely identifies the
distribution. For our example, we name this distribution CREDIT CARD STATEMENTS.

Recipient/List
Choose your recipient. For our example, we add the newly created recipient from the
drop-down menu.

Status
Two values are valid for status:
 Active indicates that the distribution is processed while the documents are loaded.
 Inactive indicates that the distribution is not processed while the documents are loaded.

Chapter 14. Report distribution 323

 Job Name
To improve ODF performance, you can use a submitted job and the persistence feature.
When you use a job name on distributions, ODF uses a feature of z/OS that allows jobs to run
in created address spaces. The ODF distribution runs under the job name that is specified.
For our example, we leave the job name value blank.

Location
The location specifies where the distribution is delivered. We select E-mail for our distribution.

The following options are available for the Location field:

 Print: The output is sent to a JES spool file.
 File: The output is sent to a generation data set (GDS) if a dataset value is specified.
Otherwise, it is sent to a TSO dataset.
 None (with “Notify by e-mail” selected): An email is sent to the recipient to notify the
recipient that the distribution is available.
 Email: The output is sent as an attachment in an email to the recipient.

Note: The “Notify by e-mail” check box is available for use with Location values of Print,
File, or None. The selection of the “Notify by e-mail” check box sends an email to the
recipient to notify them that the distribution is available.

Customer Variables
This field contains any information that you might need to pass to the customizable user exits.
For example, if this distribution requires special spool file allocation options, you can enter the
information in this field. The preallocation exit can then use the information to change the
spool file allocation parameters. For our example, we leave this field blank.

Account
This field is optional. This field specifies the name to use on the JCL job card. For our
example, we leave this field blank.

Distribution Method
The distribution method controls the scheduling and processing of the distribution. Because
we want the distribution to be processed while the documents are loaded, we select the
Loaded method.

The following distribution methods are available:

 Loaded: The distribution is scheduled for processing when the first report bundle is
archived or stored in Content Manager OnDemand. The distribution is submitted for print
processing when all of the report bundles in the distribution with a Wait/Ignore Indicator of
Wait are loaded.
 All Ready: The distribution is scheduled for processing when the ODF address space is
started. The distribution is submitted for print processing when all of the report bundles in
the distribution with a Wait/Ignore Indicator of Wait are loaded.
 External: A process outside of ODF schedules the distribution. The distribution is
submitted for print processing when all report bundles that are defined with a Wait/Ignore
Indicator of Wait are loaded.

324 IBM Content Manager OnDemand Guide

  Time of Print: The distribution is scheduled when the first report bundle of the distribution
is archived or stored in Content Manager OnDemand. Before the Time of Print time, the
distribution is submitted for print processing whenever all of the report bundles with a
Wait/Ignore Indicator of Wait are loaded. If all of the required reports are not available at
the specified time, when the Time of Print time is reached, the distribution is submitted for
print processing with whatever report bundles are available.
 Time of Day: The distribution is scheduled at the specified time of day. It is submitted for
print processing when all of the report bundles defined with a Wait/Ignore Indicator of Wait
are loaded.
 Time: The time when the distribution is processed. The default value is the current time.
This field displays only if the distribution method is set to Time of Day, or Time of Print.

Continue/Wait indicator
This option is valid only when the Distribution Method is Time of Day or Time of Print. From
the drop-down list, select either Continue to continue processing report bundles as they are
available after the Time is reached, or select Wait to wait until the next Time occurrence to
print any report bundles that become available.

Continue Max Tries

This value controls the maximum number of attempts that are made to process the report
bundles.

Manifest Indicator
This value indicates whether a manifest page, which lists the report bundles that are included
in the distribution, must be created. The manifest defaults to a separate file. If you want the
manifest in the same file as the report bundles, specify Manifest in Sysout.

Report Break Indicator

This value indicates whether the report bundles must be included in the same file or broken
up into separate files.

Print Options tab

Use the Print Options tab to specify the allocation values to use for the JES spool file. These
options do not apply to our example distribution.

14.2.5 Adding a report bundle

After you define the distribution, you must define the report bundles that are included in the
distribution. To add a report bundle, right-click the distribution that you added and then select
Add Report Bundle. See Figure 14-9 on page 326.

Chapter 14. Report distribution 325

 Figure 14-9 Adding a report bundle

Distribution Name and Recipient/Recipient List

The report bundle is created as a child object of the distribution. The values are not modifiable
and disabled in the window.

Sequence
This value identifies the sequence that the report bundles are included in the distribution. The
default is 10, and each new report bundle increments the sequence by 10. This value
provides flexibility to add report bundles without the need to renumber any other report
bundles.

Report ID
This number identifies the report to include. For our example, we select the previously added
report ID from the drop-down menu.

Wait/Ignore Indicator
When more than one report bundle is specified in the distribution, this value tells ODF
whether this report bundle must be available before the distribution is processed. A value of
Wait indicates that you wait until this report is loaded before the distribution processing
begins. A value of Ignore indicates that the distribution is processed even if this report bundle
is not available. This function is useful if documents are loaded at different times but you want
them to be processed and included in a single distribution instance.

Report Build
This field indicates whether the distribution must include the full report or if a query will be
performed and only a portion of the report will be included. When Query is selected, the SQL
source option is available to build the query. You can either type the query by using the
Keyboard option or build the SQL, as shown in Figure 14-10 on page 327. For our example,
we build a query to include only the statements for John Doe.

326 IBM Content Manager OnDemand Guide

 Figure 14-10 Building the SQL query

Additionally, users can specify a wildcard with a substring in the SQL statement. On
execution, ODF will substitute the correct portion of the recipient or recipient list name.

The format of the wildcard is shown:

 $ODF_RECIPIENT(start pos:length) where start pos is the number of the characters to
start and length is the number of characters to use. (start pos:length) is optional.
 $ODF_RECIPLIST(start pos:length) where start pos is the number of the characters to
start and length is the number of characters to use. (start pos:length) is optional.

Job Name, Location, Dataset Name, and Print Options

These fields can be used to override the values that are specified in the distribution definition.
Use this capability to specify the values at the distribution level that apply to most of your
report bundles and still customize for individual report bundles.

14.3 Defining the objects by using batch administration

ARSXML provides a batch interface to add, update, delete, or export a list of ODF objects.
We show the arsxml command and a sample XML file that is used to create each of the
objects that we added earlier.

14.3.1 Recipient
Run the following command to add a recipient:
Arsxml add -h myod -u myuser -p mypwd -v -i /recipientAdd.xml

Example 14-1 on page 328 shows the content of our example recipientAdd.xml file.

Chapter 14. Report distribution 327

 Example 14-1 recipientAdd.xml
<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ondemand.xsd">
<odfRecipient name="00001"
fullName="John Doe"
email="[email protected]"
addr1="123 Anywhere Place"
addr2="Anytown, AA 11111"
banner="true"
header1="/*************************/"
header2="/* */"
header3="/*************************/" />
</onDemand>

14.3.2 Report ID
Run the following command to add a report ID:
Arsxml add -h myod -u myuser -p mypwd -v -i /reportIDAdd.xml

Example 14-2 shows the content of our example reportIDAdd.xml file.

Example 14-2 reportIDAdd.xml

<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ondemand.xsd">
<odfReportId name="CREDIT STATEMENTs"
status="Active"
applicationGroup="Credit Card Statements"
application="Credit Card Statements" />
</onDemand>

14.3.3 Distribution and report bundle

Run the following command to create a distribution and report bundle:
Arsxml add -h myod -u myuser -p mypwd -v -i /distributionAdd.xml

Example 14-3 shows the content of our example distributionAdd.xml file.

Example 14-3 distributionAdd.xml

<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ondemand.xsd">
<odfDistribution name="CREDIT CARD STATEMENTS"
recipient="00001" s
tatus="Active"
location="E-mail document"
manifest="Manifest"
reportBreak="false"
distMethod="Loaded" >
<odfReportBundle sequence="10"
reportId="CREDIT STATEMENTS"

328 IBM Content Manager OnDemand Guide