HelloWorldOp example

The HelloWorldOp operator is an example of an operator that is derived from APT_Operator that uses arguments.

The following figure illustrates the interface schema for the HelloWorldOp operator:

Figure 1. HelloWorldOp operator interface schemaInterface schema for the HelloWorldOp operator
The definition for HelloWorldOp is explained in the following tables. The first table contains the code for the header file, and the second table has the code for the .C file. The operator takes two arguments which determine how many times the string "hello world" is printed and whether it is printed in uppercase or lowercase. The operator simply copies its input to its output.
Table 1. APT_Operator Derivation With Arguments: Header File
Comment Code 
1
 
#include <apt_framework/orchestrate.h>
 
2
 
class HelloWorldOp : public APT_Operator
{
 
4
5
 
	APT_DECLARE_PERSISTENT(HelloWorldOp);
	APT_DECLARE_RTTI(HelloWorldOp);
 
  
7
8
9
 
public:
	HelloWorldOp();
	void setNumTimes(APT_Int32 numTimes);
	void setUpperCase(bool uppercase);
 
  
11

12
13
 
protected:
	virtual APT_Status initializeFromArgs_(const APT_PropertyList &args, 
		APT_Operator::InitializeContext context);
virtual APT_Status describeOperator();
virtual APT_Status runLocally();
 
   
15
16
 
private:
	APT_Int32 numTimes_;
	bool uppercase_;
};
1
Include the orchestrate.h header file.
2
All operators are derived, directly or indirectly, from APT_Operator.
4 - 5
Declare run time type information and persistence.
7
Declare the constructor for this class.
8 - 9
Declare the C++ initialization methods for this operator. These methods are called from initializeFromArgs_().
11 -13
Declare the three virtual functions that must be overridden. The function initializeFrom Args_() is the osh initialization function which makes the operator osh aware. The function describeOperator() specifies the pre-parallel initialization steps, and runLocally() specifies the parallel execution steps.
15 -16
Declare the two member variables.
Table 2. APT_Operator Derivation With Arguments: .C File
Comment Code 
1
 
#include "hello.h"
 
3
 
#define HELLO_ARGS_DESC\
	"{uppercase={optional, description='capitalize or not'},"\
	"numtimes={value={type={int, min=1, max=10}, usageName='times'},"\
			"optional, description='number of times to print message'}}"
 
4
 
APT_DEFINE_OSH_NAME(HelloWorldOp, hello, HELLO_ARGS_DESC);
 
5
 
APT_IMPLEMENT_RTTI_ONEBASE(HelloWorldOp, APT_Operator);
 
6
 
APT_IMPLEMENT_PERSISTENT(HelloWorldOp);
 
7
 
HelloWorldOp::HelloWorldOp()
	: numTimes_(1),
	uppercase_(false)
{}
 
11
 
void HelloWorldOp::setNumTimes(APT_Int32 numTimes)
{
	numTimes_ = numTimes;
}
 
15


18
 
void HelloWorldOp::setUpperCase(bool uppercase)
{
	uppercase_ = uppercase;
}
 
19
 
APT_Status HelloWorldOp::initializeFromArgs_(const APT_PropertyList &args,	
		  APT_Operator::InitializeContext context)

{ 
	APT_Status status=APT_StatusOk; 
	if (context == APT_Operator::eRun) return status;

	for (int i = 0; i < args.count(); i++) 
	{ 
		const APT_Property& prop = args[i]; 
			if (prop.name() == "numtimes") 
				numTimes_ = (int) prop.valueList().getProperty("value", 0). 
					valueDFloat(); 
			else if (prop.name() == "uppercase") 
				uppercase_ = true; 
	} 
	return status;
}
 
33
 
void HelloWorldOp::serialize(APT_Archive& archive, APT_UInt8)
{
	archive || numTimes_;
	archive || uppercase_;
}
 
38
 
APT_Status HelloWorldOp::describeOperator()
{
	setKind(eParallel);
	setInputDataSets(1);
	setOutputDataSets(1);
	setInputInterfaceSchema("record (in:*)", 0);
	setOutputInterfaceSchema("record (out:*)", 0);
	declareTransfer("in", "out", 0, 0);
	return APT_StatusOk;
}
 
48
 
APT_Status HelloWorldOp::runLocally()
{
	APT_Status status = APT_StatusOk;
	APT_InputCursor inCur;
	setupInputCursor(&inCur, 0); 

	APT_OutputCursor outCur; 
	setupOutputCursor(&outCur, 0); 
	while(inCur.getRecord() && status == APT_StatusOk) 
	{ 
		transfer(0); 
		outCur.putRecord(); 
		int i; 
		for (i=0; i<numTimes_; i++) 
			{ 
			if (uppercase_) 
				cout << "HELLO, WORLD" << endl; 
			else 
				cout << "hello, world" << endl; 
			} 
   }
	return status; 
}
1
hello.h is the header file for this example operator.
3
A formal description of the operator arguments is given in the HELLO_ARGS_DESC string. This string enables the argv checking facility for an operator.
4
Use APT_DEFINE_OSH_NAME to connect the class name to the name used to invoke the operator from osh and pass your argument description string to DataStage.
5 - 6
APT_IMPLEMENT_RTTI_ONEBASE and APT_IMPLEMENT_PERSISTENT are required macros that implement run time information and persistent object processing.
7
HelloWorldOp::HelloWordOp() defines a constructor for the operator. All operators must have a public default constructor, even if the constructor is empty.
11 - 18
The functions setNumTimes() and setUpperCase() are the initialization methods for this operator. The method setNumTimes() sets the number of times to print the string; and the method setUpperCase() sets whether to print in uppercase letters.
19
Override initializeFromArgs_() to traverse the property list created from your argument description string and transfer information from the arguments to the class instance.
33
Override APT_Persistent::serialize() to define complex persistence in a derived class. The method is called before the operator is parallelized to archive the values of its member variables. The method is called again after parallelization to restore those variables from the archive in each parallel copy of the operator.
38
Override describeOperator() to describe the configuration information for the operator. Configuration information specifies whether the operator runs sequentially or in parallel, how many input and output data sets there are, what the input and output schemas are, and what data is transferred out of the operator.
48
Override runLocally() to define what the operator does at run time.
In this example implementation, the lines APT_InputCursor inCur and APT_OutputCursor outCur declare the input and out cursors; and the functions setupInputCursor() and setupOutputCursor() initialize them.

The while loop copies the input record to the output record and writes it to output.

Finally, the "hello, world" string is printed the specified number of times by each node.

Parent topic: APT_Operator derivation examples
Related concepts:
Supplying an argument-list description
Argument-list processor