Custom advisor methods and function calls

Use the following advisor methods and function calls in your custom advisors.

Be aware that custom advisors need to have all the required routines. Advisors must have the following base class methods:
  • A constructor routine. The constructor calls the base class constructor.
  • An ADV_AdvisorInitialize method. This method provides a way to perform additional steps after the base class completes its initialization.
  • A getLoad routine. The base advisor class performs the socket opening; the getLoad function only needs to issue the appropriate send and receive requests to complete the advising cycle.

Constructor (provided by advisor base)

public <advisor_name> { 
  String sName; 
  String sVersion; 
  int iDefaultPort; 
  int iInterval; 
  String sDefaultLogFileName; 
  boolean replace 
) 
sName
The name of the custom advisor
sVersion
The version of the custom advisor.
iDefaultPort
The port number on which to contact the server if no port number is specified in the call.
iInterval
The interval at which the advisor will query the servers.
sDefaultLogFileName
This parameter is required but not used. The only acceptable value is a null string, ""
replace
Whether or not this advisor functions in replace mode. Possible values are the following:
  • true – Replace the load calculated by the advisor base code with the value reported by the custom advisor.
  • false – Add the load value reported by the custom advisor to the load value calculated by the advisor base code.

ADV_AdvisorInitialize() method

void ADV_AdvisorInitialize()

This method is provided to perform any initialization that might be required for the custom advisor. This method is called after the advisor base module starts. In many cases, including the standard advisors, this method is not used and its code consists of a return statement only. This method can be used to call the suppressBaseOpeningSocket() method, which is valid only from within this method.

In many cases, including the standard advisors, this method is not used and its code consists of a return statement only. You can use this method to call the suppressBaseOpeningSocket method, which is valid only from within the ADV_AdvisorInitialize method.

ADVLOG() method

The ADVLOG function allows a custom advisor to write a text message to the advisor base log file. The format follows:
void ADVLOG (int logLevel, String message) 
This command has the following parameters:
logLevel
The status level at which the message is written to the log file. The advisor log file is organized in stages; the most urgent messages are given status level 0 and less urgent messages receive higher numbers. The most verbose type of message is given status level 5. These levels are used to control the types of messages that the user receives in real time (The dscontrol command is used to set verbosity). Catastrophic errors should always be logged at level 0.
message
The message to write to the log file. The value for this parameter is a standard Java string.

getAdvisorName function

The getAdvisorName function returns a Java string with the suffix portion of your custom advisor name. For example, for an advisor named ADV_cdload.java, this function returns the value cdload.

This function does not take parameters.
Avoid trouble Avoid trouble: It is not possible for this value to change during one instantiation of an advisor.gotcha

caller.getCurrentServerId()

The getCurrentServerId function returns a Java string which is a unique representation for the current server. Typically, this value changes each time you call your custom advisor, because the advisor base code queries all server machines in series.

This function takes no parameters.

caller.getCurrentClusterId()

The getCurrentClusterId function call returns a Java string which is a unique representation for the current cluster. Typically, this value changes each time you call your custom advisor, because the advisor base queries all clusters in series.

This function takes no parameters.

caller.getSocket()

The getSocket function call returns a Java socket which represents the socket opened to the current server for communication.

This function takes no parameters.

caller.getLatestLoad()

The getLatestLoad function allows a custom advisor to obtain the latest load value for a given server object. The load values are maintained in internal tables by the advisor base code and the manager daemon. This function call is useful if you want to make the behavior of one protocol or port dependent on the behavior of another. For example, you might use this function call in a custom advisor that disabled a particular application server if the Telnet server on that same machine was disabled.

The syntax is:
int caller.getLatestLoad (String clusterId, int port, String serverId)
The three arguments together define one server object.
This command has the following parameters:
clusterId
The cluster identifier of the server object for which to obtain the current load value. This argument must be a Java string.
port
The port number of the server object for which to obtain the current load value.
serverId
The server identifier of the server object for which to obtain the current load value. This argument must be a Java string. The return value is an integer.
  • A positive return value represents the actual load value assigned for the object that was queried.
  • The value -1 indicates that the server asked about is down.
  • The value -2 indicates that the status of the server asked about is unknown.

caller.receive()

The receive function gets information from the socket connection. The syntax is:
caller.receive(StringBuffer *response) 
This command has the following parameters:
response
This is a string buffer into which the retrieved data is placed. Additionally, the function returns an integer value with the following significance:
  • 0 indicates data was sent successfully.
  • A negative number indicates an error.

caller.send()

The send function uses the established socket connection to send a packet of data to the server, using the specified port. The syntax is as follows:
caller.send(String command) 
This command has the following parameters:
command
This is a string containing the data to send to the server. The function returns an integer value with the following significance:
  • 0 indicates data was sent successfully.
  • A negative number indicates an error.

getLoad()

int getLoad( int iConnectTime; ADV_Thread *caller )
This function has the following parameters:
iConnectTime
The length of time, in milliseconds, that it took the connection to complete. This load measurement is performed by the advisor base code and passed to the custom advisor code, which can use or ignore the measurement when returning the load value. If the connection fails, this value is set to -1.
caller
The instance of the advisor base class where advisor base methods are provided.Function calls available to custom advisors: The methods, or functions, described in the following sections can be called from custom advisors. These methods are supported by the advisor base code. Some of these function calls can be made directly, for example, function_name(), but others require the prefix caller. Caller represents the base advisor instance that supports the custom advisor that is being executed.

getAdviseOnPort()

The getAdviseOnPort function returns the port number on which the calling custom advisor is running.

The return value is a Java integer (int), and the function does not take parameters.
Note: It is not possible for this value to change during one instantiation of an advisor.

getAdvisorName()

The getAdvisorName function returns a Java string with the suffix portion of your custom advisor’s name. For example, for an advisor named ADV_cdload.java, this function returns the value cdload. This function takes no parameters. Note that it is not possible for this value to change during one instantiation of an advisor.

getInterval()

The getInterval function returns the advisor interval, that is, the number of seconds between advisor cycles. This value is equal to the default value set in the custom advisor’s constructor, unless the value has been modified at run time by using the dscontrol command. The return value is a Java integer (int).

The function takes no parameters.

suppressBaseOpeningSocket()

The suppressBaseOpeningSocket function call allows a custom advisor to specify whether the base advisor code opens a TCP socket to the server on the custom advisor’s behalf. If your advisor does not use direct communication with the server to determine its status, it might not be necessary to open this socket. This function call can be issued only once, and it must be issued from the ADV_AdvisorInitialize() method routine.

The function takes no parameters.


Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: March 23, 2018 0:18
File name: rprf_advcustmeth.html