Release 8.1.5
A67825-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Intelligent Agent Users Guide Release 8.1.5 A67825-01 |
|
Topics covered in this document include:
The Tcl Language with OraTcl extensions is used to write the job and events scripts. Tcl is used for the scripts because it fulfills the necessary requirements, such as:
Tcl originated with Dr. John Ousterhout from the University of California, Berkeley, California. Tcl, current release version 7.5, stands for Tool Command Language.
Tcl is both a language and a library. Tcl is a simple textual language that is intended primarily for issuing commands to interactive programs, such as text editors, debuggers, illustrators, and shells. Tcl has a simple syntax and is programmable. Tcl users can write command procedures to provide more powerful commands than those in the built-in set.
Tcl is also a library package that can be embedded in application programs. The Tcl library consists of a parser for the Tcl language, routines to implement the Tcl built-in functions, and procedures that allow each application to extend Tcl with additional commands specific to that application. The application program generates Tcl commands and passes them to the Tcl parser for execution. Commands may be generated by reading characters from an input source, or by associating command strings with elements of the application's user interface, such as menu entries, buttons, or keystrokes. When the Tcl library receives commands it parses them into component fields and executes built-in commands directly. For commands implemented by the application, Tcl calls back to the application to execute the commands. In many cases commands will invoke recursive invocations of the Tcl interpreter by passing in additional strings to execute. Procedures, looping commands, and conditional commands all work in this way.
An application program gains several advantages by using Tcl for its command language.
Tcl was designed with the philosophy that one should actually use two or more languages when designing large software systems. One for manipulating complex internal data structures, or where performance is key, and another, such as Tcl, for writing small scripts that tie together the c programming pieces and provide hooks for others to extend. For the Tcl scripts, ease of learning, ease of programming and ease of integrating are more important than performance or facilities for complex data structures and algorithms. Tcl was designed to make it easy to drop into a lower language when you come across tasks that make more sense at a lower level. In this way, the basic core functionality can remain small and one need only bring along pieces that one particular wants or needs. For more information on Tcl/Tk, access the following web sites:
World Wide Web site locations often change and the addresses may not be available in the future.
Agent jobs and event scripts require both host system access for handling files and devices, launching programs, executing operating system functions, and accessing Oracle databases. OraTcl was developed to extend Tcl for Oracle usage and SNMP accessing. The categories of OraTcl functions are:
For descriptions of the OraTcl functions and variables, see OraTcl Functions and Parameters on page 5-64.
The following example illustrates the basic use of OraTcl.
#!/usr/local/bin/Tcl -f
#
# monthly_pay.Tcl
#
# usage: monthly_pay.Tcl [connect_string]
# or Tcl -f monthly_pay.Tcl [connect_string]
#
# sample program for OraTcl
# Tom Poindexter
#
# example of sql, pl/sql, multiple cursors
# uses Oracle demo table SCOTT.EMP
# uses id/pass from command line,
# or "scott/tiger" if not specified
#
# this example does not illustrate efficient sql!
# a simple report is produced of the monthly payroll
# for each jobclass
#
global oramsg
set find_jobs_sql { select distinct job from SCOTT.EMP }
set monthly_pay_pl {
begin
select sum(sal) into :monthly
from SCOTT.EMP
where job like :jobclass;
end;
}
set idpass $argv
if {[string length $idpass] == 0} {
set idpass "scott/tiger"
}
set lda [oralogon $idpass]
set cur1 [oraopen $lda]
set cur2 [oraopen $lda] orasql $cur1 $find_jobs_sql
set job [orafetch $cur1]
while {$oramsg(rc) == 0} {
oraplexec $cur2 $monthly_pay_pl :monthly "" :jobclass "$job"
set total_for_job [lindex [orafetch $cur2] 0]
puts stdout "Total monthly salary for job class $job = \$ $total_for_job"
set job [orafetch $cur1]
}
oraclose $cur1
oraclose $cur2
oralogoff $lda
exit
OraTcl creates and maintains a Tcl global array oramsg to provide feedback of Oracle server messages. oramsg is also used to communicate with the OraTcl interface routines to specify NULL return values and LONG limits. In all cases except for NULLVALUE and MAXLONG, each element is reset to NULL upon invocation of any OraTcl command, and any element affected by the command is set. The oramsg array is shared among all open OraTcl handles.
oramsg should be defined with the global statement in any Tcl procedure that needs it.
The following are oramsg elements.
The character set of the agent, such as US7ASCII. This is used with the convertin and convertout verbs to convert character sets. See convertin on page 5-66 and convertout on page 5-67.
The character set of the database, such as US7ASCII. This is used with the convertin and convertout verbs to convert character sets. See convertin on page 5-66 and convertout on page 5-67.
A Tcl list of the lengths of the columns returned by oracols. collengths is only set by oracols.
A Tcl list of the precision of the numeric columns returned by oracols. colprecs is only set by oracols. For non-numeric columns, the list entry is a null string.
A Tcl list of the scale of the numeric columns returned by oracols. Colscales is only set by oracols. For non-numeric columns, the list entry is a null string.
A Tcl list of the types of the columns returned by oracols. coltypes is only set by oracols. Possible types returned are: CHAR, VARCHAR2 (Version 7), NUMBER, LONG, rowid, DATE, RAW, LONG_RAW, MLSLABEL, RAW_MLSLABEL, or unknown.
The message text associated with rc. Because the oraplexec function may invoke several SQL statements, there is a possibility that several messages may be received from the server.
Indicates the handle of the last OraTcl function. The handle, a mapping in memory used to track commands, is set on every OraTcl command except where an invalid handle is used.
The job Id of the current job. Defined for job scripts only.
The NLS language of the Console, such as AMERICAN_AMERICA.US7ASCII.
Can be set by the programmer to limit the amount of LONG or LONG RAW data returned by orafetch. The default is 32K Bytes. The maximum is 64K (Version 6) or 2147483647 (Version 7) bytes. Any value less than or equal to zero is ignored. Any change to maxlong becomes effective on the next call to orasql. See notes on MAXLONG usage with orafetch.
Can be set by the programmer to indicate the string value returned for any NULL result. Setting oramsg(nullvalue) to DEFAULT will return 0 for numeric null data types, such as INTEGER, FLOAT, and MONEY, and a NULL string for all other data types. NULLVALUE is initially set to default.
The number OCI code of the last OCI function called by OraTcl. See the Programmer's Guide to the Oracle Call Interface for descriptions.
Contains the object upon which this script is acting. Defined for event scripts only.
The ORACLE_HOME directory.
A Tcl list of the SNMP index values from the snmp.ora configuration file.
A Tcl list that contains the names of the job's input files. Probably most jobs will not need input files, but a job which invokes SQL*Plus with a SQL script, or Export with a specification file, would use this feature. Defined for job scripts only.
Indicates the results of the last SQL command and subsequent orafetch processing. rc is set by orasql, orafetch, oraplexec, and is the numeric return code from the last OCI library function called by an OraTcl command.
See the Oracle Error Messages and Codes Manual for detailed information.Typical values are listed in Table 5-1, "Error Messages".
The number of rows affected by an insert, update, or delete in an orasql command, or the cumulative number of rows fetched by orafetch.
The numeric OCI code of the last SQL function performed. See the Programmer's Guide to the Oracle Call Interface for descriptions.
The time at which the job was scheduled to be started. Defined for jobs only.
Tcl scripts are used by the intelligent agent for jobs and events. While both are Tcl scripts, they are distinct in the agent and in the user interface.
Jobs are scripts scheduled to run once or multiple times. They typically cause side-effects, such as starting up a database, performing a backup, or sending output to the screen via the puts command, and can potentially have long execution times. Jobs can have output files and input files, such as a SQL script, while event scripts do not. Note that output files on Unix, DOS, or OS/2 are stdout redirected.
Event scripts, on the other hand, are used uniquely for detecting exceptions. A Tcl event script can monitor databases, host systems, or SQL*Net services by using a variety of means. If the script determines that a certain condition has occurred, it can send a return code to the agent that states the severity of the event. Event scripts tend to run more frequently than jobs and so they are expected to have relatively short execution times. Also, it is assumed that event scripts do not cause any side effects.
While both jobs and events use Tcl to accomplish their tasks, they are very different in nature and as such have different execution environments. Specifically, on UNIX systems, jobs are forked into a separate process, while events are usually executed in-line with the agent code.
The Tcl interpreter state is saved between executions and the value of Tcl global variables is preserved, for inline event scripts only, to give the illusion of a virtual process. This allows an event script to maintain a history so that the event does not get raised over and over again. For example, after you have notified the console that a value has gone above 90, you can refrain from notifying it again until the value goes below 80 and then back above 90. Database connections using the oralogon function are cached across all inline event scripts, so that repeated event scripts that use the same connect string can utilize the same connection.
Not all commands and global variables are available to both jobs and events. Jobs will not have the oraobject global variable that tells an event what service it is running against. Events will not have the orainput global that jobs use for SQL*Plus scripts.
When a user registers for an event or schedules a job, the user's language preference is available to the agent. There is a special remote procedure call which reports the language and current address of each console user. The agent proceeds to issue an ALTER SESSION command to the specified language every time the oralogon function is called. This means that any subsequent messages or output coming from the Oracle server will be in the user's language. In addition, character set conversion is explicitly not done on the agent, so that the Console can do it on the user's side.
If an event script or a job script fails execution, an error message is sent back to the Console in the user's language. Typically this will be an Oracle message returned by one of the Oracle Tcl extensions, if the verb was given inadequate parameters. For example oralogon might return the error: "ERROR: ORA-01017: invalid username/password; logon denied" if it is given an incorrect connect string. However, the error message could also be a Tcl specific message, such as: "ERROR: Tcl-00456: division by zero error", which will be stored in a message file and thus can be returned in the user's preferred language. The default language used by the agent will be American English if no user language preference is specified or if an error message text does not exist in the user's language.
This section lists the OraTcl functions and parameters. Functions or other words that appear in OraTcl syntax are shown in this font: function. Parameters in square brackets `[option]' are optional, and the `|' character means `or'. All parameters are passed into the functions and are IN mode.
|
|
|
|
|
The following parameters are used in multiple OraTcl functions and the descriptions are provided in this section.
The column name that is the LONG or LONG RAW column.
A valid Oracle database connect string, in one of the forms:
name | name/password | name@n:dbname | name/password@n:dbname
destaddress is the destination address of the agent.
The name of the file that contains the LONG or LONG RAW data to write into the column or the name of the file in which to write the LONG or LONG RAW data.
A valid cursor-handle previously opened with oraopen. The handle is a mapping in memory used to track functions.
The Oracle database rowid of an existing row, and must be in the format of an Oracle rowid datatype.
The Oracle database table name that contains the row and column.
This function returns the contents of a file.
catfile filename
The file that you want to display.
catfile /tmp/files1 or c:/orant/sysman/admin/vobmgr.log
This function returns the full pathname for a file given a list of file name components.
concatname components
A list containing the filename and each directory name where the file is located.
concatname [list $oramsg(orahome) network agent]
This function converts the parameter string from the client's (Console) character set to the destination character set. The function returns the converted string.
convertin dest_characterset string
Destination character set. For database specific jobs or events, use $oramsg(db_characterset). For node specific jobs or events, use $oramsg(agent_characterset). See oramsg Elements on page 5-58.
The string that is converted.
The client and the agent node may use different languages or character sets. It is the responsibility of the Tcl script developer to perform the character set conversion. In general, all the job or event input parameters should be converted unless they are guaranteed to be ASCII.
This function converts the parameter string from the destination character set to the client's (Console) character set. The function returns the converted string.
convertout dest_characterset string
Destination character set. For database specific jobs or events, use $oramsg(db_characterset). For node specific jobs or events, use $oramsg(agent_characterset). See oramsg Elements on page 5-58.
The string that is converted.
The client and the agent node may use different languages or character sets. It is the Tcl script developers' responsibility to perform the character set conversion. In general all the job or event output should be converted unless they are guaranteed to be ASCII.
This function returns disk usage information on a specified file. The output is four lists: file systems, total space, available space, and mount points.
diskusage file
A file name. You can omit the filename to display information on the entire file system.
diskusage [list /tmp]
This function writes a string to a file.
echofile string filename
The string you want to write to the file.
The name of the file where you want to store the string.
echofile asdf /tmp/temp
This function executes the Oracle Export database tool.
export arguments
These are the command-line arguments that are used by the Export tool.
For information on Export, see the Oracle7 Server Utilities User's Guide.
This function executes the Oracle Import database tool.
import arguments
These are the command-line arguments that are used by the Import tool.
For information on Import, see the Oracle7 Server Utilities User's Guide.
This function executes the Oracle SQL*Loader database tool.
loader arguments
These are the command-line arguments that are used by the SQL*Loader tool.
For information on SQL*Loader, see the Oracle7 Server Utilities User's Guide.
This function returns message text in the client's (Console) language for the given product name, facility and message number. The output is in the format of "FACILITY-ERROR : MESSAGE TEXT".
msgtxt product facility error_no
Product name. For example, rdbms.
Facility name. For example, ora.
Error number. For example, 1101.
This function is used to put out error messages in the job output file. The message will be displayed in the client's (Console) language.
This function returns a message in the client's (Console) language for the given product name, facility and message number. The output is in the format of "MESSAGE TEXT".
msgtxt1 product facility error_no
Product name. For example, rdbms.
Facility name. For example, ora.
Error number. For example, 1101.
This function is used to put out confirmation messages in the job output file. The message will be displayed in the client's (Console) language.
This function moves a file to a different location/name.
mvfile filename destination
The name of the file you want to move or rename.
The new destination/name.
None
This function enables or disables automatic commit of SQL data manipulation statements using a cursor opened through the connection specified by logon-handle.
oraautocom logon-handle {on | off}
See Common Parameters on page 5-65.
oraautocom raises a Tcl error if the logon-handle specified is not open.
Either on or off must be specified. The automatic commit feature defaults to off.
This function cancels any pending results from a prior orasql function that use a cursor opened through the connection specified by logon-handle.
oracancel logon-handle
See Common Parameters on page 5-65.
oracancel raises a Tcl error if the logon-handle specified is not open.
This function closes the cursor associated with logon-handle.
oraclose logon-handle
See Common Parameters on page 5-65.
oraclose raises a Tcl error if the logon-handle specified is not open.
This function returns the names of the columns from the last orasql, orafetch, or oraplexec function as a Tcl list. oracols may be used after oraplexec, in which case the bound variable names are returned.
oracols logon-handle
See Common Parameters on page 5-65.
oracols raises a Tcl error if the logon-handle specified is not open.
The oramsg array index collengths is set to a Tcl list corresponding to the lengths of the columns; index coltypes is set to a Tcl list corresponding to the types of the columns; index colprecs is set to a Tcl list corresponding to the precision of the numeric columns, other corresponding non-numeric columns are a null string (Version 7 only); index colscales is set to a Tcl list corresponding to the scale of the numeric columns, other corresponding non-numeric columns are a null string (Version 7 only).
This function commits any pending transactions from prior orasql functions using a cursor opened with the connection specified by logon-handle.
oracommit logon-handle
See Common Parameters on page 5-65.
oracommit raises a Tcl error if the logon handle specified is not open.
This function retrieves SNMP MIB values.
oradbsnmp get | getnext object_Id
object_Id can be either an actual MIB object Id, such as "1.3.6.1.2.1.1.1.0", or an object name with a possible index attached to it, such as "sysDescr" or "sysDescr.0".
oradbsnmp is a function for retrieving SNMP MIB values maintained by the agent, such as the RDBMS public MIB or the Oracle RDBMS private MIB. It does not write to the well-known UDP port for SNMP and obtains its values directly from the agent's internal data structures. It works if the host does not have an SNMP master agent running on it. See orasnmp on page 5-83 for more details on what get and getnext do. There are several reasons why oradbsnmp should be used instead of fetching the values from V$ tables with SQL commands:
This function forces a Tcl script to fail.
orafail errormsg
errormsg can either be a quoted string of text or a string of the form: FAC-XXXXX where XXXXX is an Oracle message number for the given facility, such as VOC-99999.
The error message will be used for display purposes on the client side.
This function returns the next row from the last SQL statement executed with orasql as a Tcl list.
orafetch logon-handle [commands]
See Common Parameters on page 5-65.
The optional commands allows orafetch to repeatedly fetch rows and execute commands for each row.
orafetch raises a Tcl error if the logon-handle specified is not open.
All returned columns are converted to character strings. A null string is returned if there are no more rows in the current set of results. The Tcl list that is returned by orafetch contains the values of the selected columns in the order specified by select.
Substitutions are made on commands before passing it to Tcl_Eval() for each row. orafetch interprets @n in commands as a result column specification. For example, @1, @2, @3 refer to the first, second, and third columns in the result. @0 refers to the entire result row, as a Tcl list. Substitution columns may appear in any order, or more than once in the same command. Substituted columns are inserted into the commands string as proper list elements. For example, one space will be added before and after the substitution and column values with embedded spaces are enclosed by {} if needed.
A Tcl error is raised if a column substitution number is greater than the number of columns in the results. If the commands execute a break, orafetch execution is interrupted and returns with Tcl_OK. Remaining rows may be fetched with a subsequent orafetch function. If the commands execute return or continue, the remaining commands are skipped and orafetch execution continues with the next row. orafetch will raise a Tcl error if the commands return an error. Commands should be enclosed in "" or {}.
OraTcl performs conversions for all data types. Raw data is returned as a hexadecimal string, without a leading "0x". Use the SQL functions to force a specific conversion.
The oramsg array index rc is set with the return code of the fetch. 0 indicates the row was fetched successfully; 1403 indicates the end of data was reached. The index of rows is set to the cumulative number of rows fetched so far.
The oramsg array index maxlong limits the amount of long or long raw data returned for each column returned. The default is 32768 bytes. The oramsg array index nullvalue can be set to specify the value returned when a column is null. The default is "0" for numeric data, and "" for other datatypes.
This function is used by jobs to copy a remote file into a local file.
oragetfile destaddress remotefile localfile [BIN]
See Common Parameters on page 5-65.
remotefile is the name of the file that is the source of the copy.
localfile is the name of the file that is the target of the copy.
oragetfile fetches the file remotefile into the local file localfile from the agent at destaddress. If the BIN argument is specified, the file is transferred in binary mode.
destaddress may be obtained from the orainfo function. Note that the address provided must be the spawn address of the agent, the special address on which it listens for file transfer requests, and not the normal address used for all other RPCs.
For more information on the address of an intelligent agent, see the chapter on configuring the agent in the Oracle Enterprise Manager Installation Guide.
This function is used by jobs to get configuration information.
orainfo destaddress
See Common Parameters on page 5-65.
orainfo fetches agent configuration information from the agent at destaddress. If destaddress is not present, then it is fetched from the agent on the local machine. The agent configuration is a Tcl list, as follows:
This function is used by a job to send intermediate output back to the Console.
orajobstat destaddress string
See Common Parameters on page 5-65.
string can either be a quoted string of text or a string of the form: FAC-XXXXX where XXXXX is an Oracle message number for the given facility, such as VOC-99999. The string is used for display on the client side.
destaddress is the address of the agent, not the daemon. This function is issued from a job process, not from within an agent process. The agent's address can be obtained with orainfo.
This function logs off from the Oracle server connection associated with logon-handle.
oralogoff logon-handle
See Common Parameters on page 5-65.
oralogoff raises a Tcl error if the logon handle specified is not open. oralogoff returns a null string.
This function connects to an Oracle server using connect_string.
oralogon connect_string
See Common Parameters on page 5-65.
A logon-handle is returned and should be used for all other OraTcl functions using this connection that require a logon-handle. Multiple connections to the same or different servers are allowed, up to a maximum of six total connections.
The connection limit is covered in the operating system-specific notes. When oralogon is used in an event script, it benefits from the connection cache. It will usually be able to reuse the connections opened by other event scripts against the same database. See NLS Issues and Error Messages on page 5-63 for details. oralogon raises a Tcl error if the connection is not made for any reason, such as login incorrect or network unavailable. If connect_string does not include a database specification, the value of the environment variable ORACLE_SID is used as the server.
This function opens an SQL cursor to the server. oraopen returns a cursor to be used on subsequent OraTcl functions that require a logon-handle.
oraopen logon-handle
See Common Parameters on page 5-65.
oraopen raises a Tcl error if the logon-handle specified is not open. Multiple cursors can be opened through the same or different logon handles, up to a maximum of 25 total cursors.
This function executes an anonymous PL block, optionally binding values to PL/SQL variables.
oraplexec logon-handle pl_block [:varname value ...]
See Common Parameters on page 5-65.
pl_block may either be a complete PL/SQL procedure or a call to a stored procedure coded as an anonymous PL/SQL block.
:varname value are optional pairs.
oraplexec raises a Tcl error if the logon-handle specified is not open, or if the PL/SQL block is in error. oraplexec returns the contents of each :varname as a Tcl list upon the termination of PL/SQL block.
Optional :varname value pairs may follow pl_block. Varnames must be preceded by a colon, and match the substitution names used in the procedure. Any :varname that is not matched with a value is ignored. If a :varname is used for output, the value should be coded as a null string, "".
The oramsg array index rc contains the return code from the stored procedure.
This function reads the contents of a LONG or LONG RAW column and write results into a file.
orareadlong logon-handle rowid table column filename
See Common Parameters on page 5-65.
orareadlong returns a decimal number upon successful completion of the number of bytes read from the LONG column.
orareadlong raises a Tcl error if the logon-handle specified is not open, or if rowid, table, or column are invalid, or if the row does not exist.
orareadlong composes and executes an SQL select statement based on the table, column, and rowid. A properly formatted Rowid may be obtained through a prior execution of orasql, such as "SELECT rowid FROM table WHERE ...".
This function is used by jobs to report an unsolicited event to the agent and Event Management system in the Console. The oemevent executable can also be used.
orareportevent eventname object severity message [results]
eventname is the name of the event. This is the four-part name of the event in the form:
/vendor/product/category/name
You can enter any character string but all four parts and the forward slashes (/) are required.
The first two levels of name have special significance and have many predefined strings that Oracle script writers must use:
The eventname is assumed to be in 7-bit ASCII, so that it never changes regardless of platform or language. See eventdef.tcl in the ORACLE_HOME\net8\admin directory (Oracle Enterprise Manager release 1.5.0 on a Windows NT platform) for a list of defined event names.
The actual event script name may be shortened, upper-cased, or manipulated in other ways to make it a legal, unique filename on a given platform. The format is operating system-specific. For example, /oracle/rdbms/security/SecurityError can be stored as $oracle_home/network/agent/events/oracle/rdbms/security/securityerror.tcl on a Unix system.
object is the name of the object that the event is monitoring, such as the database or service name listed in the snmp.visibleservices parameter in the snmp.ora file, or $oramsg(nodename).
severity is the level of severity of the event. For orareportevent, the value is 1 (warning), 2 (alert), or -1 (clear). For oemevent, this is the literal text string alert, warning, or clear.
message is a quoted text string that is displayed in the Console, such as "File not found."
results is any results that may occur from the event. This is a Tcl list with the specific results for the event, such as the tablespace in error or the user who had a security violation.
This is the method for any job to report an unsolicited event to the agent, and back to the Console. . For information on the Event Management system, see the Oracle Enterprise Manager Administrator's Guide.
This function rolls back any pending transactions from prior orasql functions that use a cursor opened through the connection specified by logon-handle.
oraroll logon-handle
See Common Parameters on page 5-65.
oraroll raises a Tcl error if the logon handle specified is not open.
This function causes the Tcl script to pause for a number of seconds.
orasleep seconds
orasleep calls slcsleep() for the required number of seconds. There is no default, minimum, or maximum value.
This function performs either an SNMP get or getnext operation on the object specified by object_id.
orasnmp get | getnext object_Id
The object_Id can be either an actual MIB object Id, such as "1.3.6.1.2.1.1.1.0", or an object name with an index attached to it, such as "sysDescr" or "sysDescr.0".
Object names come from MIB text files. A full network manager, such as OpenView, has a MIB compiler that accepts MIB files and parses the ASN.1, creating a database of all objects in all the MIBs. The agent needs to be simpler. There is a standard configuration directory which contains one or more two-column ASCII files of the format:
"rdbmsDbPrivateMibOID", "1.3.6.1.2.1.39.1.1.1.2",
"rdbmsDbVendorName", "1.3.6.1.2.1.39.1.1.1.3",
"rdbmsDbName", "1.3.6.1.2.1.39.1.1.1.4",
"rdbmsDbContact", "1.3.6.1.2.1.39.1.1.1.5",
....
The Tcl interpreter reads these files and does a binary search on them at runtime to resolve an object name to an object_Id.
The index values to use for Oracle services are configured via the snmp.ora file. These indices can also be obtained from the oraindex global variable. See Server Message and Error Information on page 5-58.
The result of orasnmp is a Tcl list of the form:
{object_id value}
where object_Id is the object id associated with value. In the case of an orasnmp get, object_Id is the same as object, while for a getnext, it would be the next logical object_Id. It is assumed that the orasnmp operation applies to the local host only. The function actually sends out an SNMP query to the well-known SNMP port on the local host, so it is possible to query MIB variables other than Oracle's, such as those of the host or other applications that support SNMP. An SNMP master agent needs to be running on the local host for this function to work. See oradbsnmp on page 5-73 for an optimized way to retrieve the Oracle database MIB objects. If the master agent is not running, this function fails.
This function sends the Oracle SQL statement SQL statement to the server.
orasql logon-handle sql_stmt
See Common Parameters on page 5-65.
sql_stmt is a single, valid SQL statement.
logon-handle must be a valid handle previously opened with oraopen. orasql raises a Tcl error if the logon-handle specified is not open, or if the SQL statement is syntactically incorrect.
orasql will return the numeric return code 0 on successful execution of the SQL statement. The oramsg array index rc is set with the return code; the rows index is set to the number of rows affected by the SQL statement in the case of insert, update, or delete. Only a single SQL statement may be specified in sql_stmt. orafetch allows retrieval of return rows generated. orasql performs an implicit oracancel if any results are still pending from the last execution of orasql.
Table inserts made with orasql should follow conversion rules in the Oracle SQL Reference manual.
This function starts an Oracle database instance.
orastart connect_string [init_file] [SYSDBA|SYSOPER] [RESTRICT] [PARALLEL] [SHARED]
See Common Parameters on page 5-65.
init_file is the path to the init.ora file to use.
The default for init_file is:
ORACLE_HOME/dbs/init${ORACLE_SID}.ora
[SYSDBA|SYSOPER] are role flags for the user starting up the database. [RESTRICT] [PARALLEL] [SHARED] are database options. If [RESTRICT] is specified, database is started in restricted mode.
This function stops an Oracle database instance.
orastop connect_string [SYSDBA|SYSOPER] [IMMEDIATE|ABORT]
See Common Parameters on page 5-65.
[SYSDBA|SYSOPER] are role flags for the user shutting down the database. [IMMEDIATE|ABORT] are the shutdown mode flags.
Shutdown normal might be expected to fail every time, because the agent maintains its own connection to the database, but we send a special RPC to the agent when this is done, which causes it to disconnect from the database.
This function returns the current date and time.
oratime
None
None
This function writes the contents of a file to a LONG or LONG RAW column.
orawritelong logon-handle rowid table column filename
See Common Parameters on page 5-65.
orawritelong composes and executes an SQL update statement based on the table, column, and rowid. orawritelong returns a decimal number upon successful completion of the number of bytes written to the LONG column. A properly formatted ROWID may be obtained through a prior execution of the orasql function, such as "SELECT rowid FROM table WHERE ....".
orawritelong raises a Tcl error if the logon-handle specified is not open, or if rowid, table, or column are invalid, or if the row does not exist.
This function removes a file.
rmfile filename
This is the file that you want to remove.
None
This function returns a directory name that is used to store temporary files.
tempdir
On Unix platforms, the tempdir is usually /tmp. On Windows NT systems, the tempdir is usually \temp.
This function returns a temporary filename with the given extension. The filename is generated using the timestamp.
tempfile extension
This is the file extension of the temporary file.
tempfile dd
returns the following on a Unix platform
/tmp/143153.dd
Certain advanced events must know the version of the database it is working on.
For the 8.1.3 Agent on NT, the version information is not returned using the Tcl verb [DB_VERSION] if you start the agent service before starting the database or if you start the agent service when the database or the listener servicing the database is down. Please make sure that the database and listener are up before starting the agent service.
For the 8.1.5 agent on Solaris, the version information is not returned using the Tcl verb [DB_VERSION] if you start the agent service before starting the database or if you start the agent service when the database or the listener servicing the database is down and you have not set your snmp_rw.ora file to recognize the state changes of the database.
To setup the 8.1 Solaris agent to recognize the change in the state of the database, ensure that you have the following entry in the snmp_rw.ora file:
dbsnmp.noheuristic=1
To check the version of the database, type the following in the ORATCLSH, making sure that the oramsg (oraindex) is set to the correct database index of a running database:
ORATCLSH>oradbsnmp get applVersion.$oramsg(oraindex)
