APL Collection Strategy configurations are used on top of pre-defined collection strategies to customize how files are collected from the local file system.

Note!

The APL function blocks that are described in this chapter are automatically invoked from the collection agent and cannot be called manually.

The following functions blocks may be used in the APL Collection Strategy code:

The initialize, deinitialize, begin, commit, and rollback function blocks are equivalent to the corresponding APL function blocks described in Function Blocks.

The collection specific functions blocks are invoked in the following order:

prepareBaseDirList
accept
filterFiles
preFileCollection
postFileCollection

Note!

During run-time, when each of the functions blocks are invoked, the workflow first runs the function blocks base part and then it executes your APL extension code.

The following APL functions cannot be used within an APL Collection Strategy configuration.

udrRoute
mimSet
mimPublish
cancelBatch
hintEndBatch

In the following APL functions you cannot assign a persistent variable with a value. For information about persistent variables, see Variables and Variable Scope

initialize
deinitialize
commit
rollback

initialize

The initialize function block is used to prepare for the collection and set up an environment to be used in a later stage, when the batch workflow is executed.

void initialize()

deinitialize

The deinitialize function block is used to clean-up and close resources.

void deinitialize()

prepareBaseDirList

The prepareBaseDirList function block prepares for a list of base directories. A base directory is the directory that includes the files to be collected. This directory is defined when configuring an agent's Base Collection Strategy. Base directory paths can be added, removed, and modified.

The prepareBaseDirList function block is invoked by the Collection agent right after the collection preparation activities that were initiated by the initialize function.

void prepareBaseDirList( list<string>  dirList  )

Parameter Description

dirList

This parameter is used to define one or more collection sources. The collection order of the files is defined using the filterFiles function.

The dirList parameter refers to a list that, by default, contains the directory that is defined when configuring an agent's Base Collection Strategy.

The dirList parameter is an in/out parameter that serves both as input and output values for the prepareBaseDirList function.

In the following example, prepareBaseDirList adds a subdirectory named sub to the directory that is already on the base directories list. For example: If /home/in is a directory that is on the directory list, the prepareBaseDirList function adds /home/in/sub to the directory list.

Example - Using prepareBaseDirList

void prepareBaseDirList(list<string> dirList) {
    string dir = listGet(dirList, 0);
    string subDir = dir + "/sub";
    listAdd(dirList, subDir);
}

accept

The collection agent processes the base directory and its included files and creates an internal file list including all files to be collected. The accept function block is invoked by the collection agent each time a new file is about to be added to the list, and, based on each file's fileInfo object, either accepts or rejects the file.

boolean accept
( FileInfo  file  )

Parameter Description

file

The file parameter includes the properties of the file to collect or a directory where files are stored.

The FileInfo object includes:

Item	Description
`isDirectory(boolean)`	Set to True if FileInfo represents a directory.
`isFile(boolean)`	Set to True if FileInfo represents a file.
`name(string)`	The name of the file or directory
`size(long)`	The size of the file or directory
`timestamp(long)`	The timestamp for when the file or directory was last modified

Returns

True if the file shall be added to the list of files that are about to be collected

Example - Using accept

In this example, only files that have a name that starts with "INFILE_ascii" are collected.

boolean accept(FileInfo file) {
    if(file.isFile) { 
        if ( strStartsWith(file.name, "INFILE_ascii") ) {
            return true;
        } else {
            return false;
        }
     } else{
        return false;
    }
}

filterFiles

The filterFiles function block is invoked by the collection agent right after the accept function has been executed and when the list of files has been created. Files to collect can be removed, but not added or modified. Collection order can be modified by sorting the list.

void filterFiles
( list<FileInfo>  fileInfoList  )

Parameter:

Parameter	Description
`fileInfoList`	The `fileInfoList` parameter contains a reference to the list that includes the files to collect. `fileInfoList` is an in/out parameter that serves both as input and output values for the `filterFiles` function.

In the following example, file1 is not collected if there is another file with the same name that includes the prefix "ignore_" (ignore_file1) in the collected directory.

Example - Using filterFiles

In this example, file1 is not collected if there is another file with the same name that includes the prefix "ignore_" (ignore_file1) in the collected directory.

void filterFiles(list<FileInfo> fileInfoList) {

    // put the files into a map
    string ignorePrefix = "ignore_";
    map<string, FileInfo> fileInfoMap = mapCreate(string, FileInfo);
    int i = listSize(fileInfoList);
    while(i > 0) {
        i = i - 1;
        FileInfo fileInfo = listGet(fileInfoList, i);
        mapSet(fileInfoMap, fileInfo.name, fileInfo);
    }
    
    // Remove from the map files that are indicated as files 
    // that should be ignored, along with their ignore_ indicator 
    // files .
    
    i = listSize(fileInfoList);
    while(i > 0) {
        i = i - 1;
        FileInfo fileInfo = listGet(fileInfoList, i);
        
        // check if the filename start with the ignore prefix
        boolean ignore = strStartsWith(fileInfo.name, ignorePrefix);
        
        if(ignore) {
            string fileToIgnore = strSubstring(fileInfo.name, 
            strLength(ignorePrefix), strLength(fileInfo.name));
            mapRemove(fileInfoMap, fileInfo.name);   
            mapRemove(fileInfoMap, fileToIgnore);   
        }
    }
    
    // put the remaining files in the fileInfoList
    listClear(fileInfoList);
    
    list<FileInfo> remainingFiles = mapValues(fileInfoMap);
    i = listSize(remainingFiles);
    while(i > 0) {
        i = i - 1;
        listAdd(fileInfoList, listGet(remainingFiles, i));
    }
}

preFileCollection

The preFileCollection function block is invoked by the Collection agent right before a file is collected.

void preFileCollection
( string  fileName  )

Parameter	Description
`fileName`	The `fileName` parameter includes the name of the file to be collected.

postFileCollection

The postFileCollection function block is invoked by the Collection agent right after a file has been collected.

void postFileCollection
( string  fileName  )

Parameter	Description
`fileName`	The `fileName` parameter includes the name of the file that has been collected.

begin

The begin function block is invoked by the Collection agent during the Begin Batch processing phase and marks a start point for the file based transaction handling. On severe errors, such as when a transaction fails, the APL command abort("reason") should be invoked.

void begin
( long  transactionID  )

Parameter	Description
`transactionID`	The `transactionID` parameter is the identifier of this transaction.

commit

The commit function block is invoked by the Collection agent right after the End Batch processing phase and marks the end of the file-based transaction handling. On severe errors, such as when a transaction fails, the APL command abort("reason") should be invoked.

void commit
( long  transactionID ,                
boolean  isRecover  )

Parameter	Description
`transactionID`	The `transactionID` parameter is the identifier of this transaction.
`isRecover`	The `isRecover` parameter is set to "true" if this is a recover operation. If the last commit failed, a commit recover operation is executed upon workflow startup.

rollback

The rollback function block is invoked in case of a system failure, right after the End Batch processing phase. On severe errors, such as when a transaction fails, the APL abort("reason") command should be invoked.

void rollback
( long  transactionID ,                
boolean  isRecover  )

Parameter	Description
`transactionID`	The `transactionID` parameter is the identifier of this transaction.
`isRecover`	The `isRecover` parameter is set to "true" if this is a recover operation. If the last rollback failed, a rollback recover operation is executed upon workflow startup.

Browser not supported