Plsqlap_Record_API Overview

NOTE: This package is obsolete and has been deprecated. The new package, Plsqlap_Document_API, should be used instead. The Plsqlap_Record_API package will be remained "as is" but will not be maintained any more, which means that possible future problems related to this package should be solved by re-writing code to use the new, Plsqlap_Document_API package.

The Plsqlap_Record_API package is used to create and manipulate records. Records are the dynamic data structures underlying the object views used in Extended Server. This package has no access to meta data. It is the responsibility of the applications using the package to create the records according to the meta data definitions. Any discrepancy from the meta data definition will result in runtime errors.

Record handling

New_record will reserve space in a temporary tablespace, and code which calls New_record without calling Clear_Record will cause superfluous resource consumption. To enable server reliability and stability, Clear_Record must be called when finished processing a record.

Some Plsqlap_Server_API Invoke/Post methods will implicitly call Clear_Record. Please check the "Record Handling" guidelines for respective Plsqlap_Server_API method.

Data Types and Constants

| Type List | Global constant variable  list |

Methods

Method	Description
Procedure Add_Aggregate	Add a record to a record attribute of type aggregate
Procedure Add_Array	Add a record to a record attribute of type array.
Function Check_Elements (Record, Name)	Checks if attribute with given name exists in record.
Procedure Clear_Dirty (Record)	Changes the record attribute dirty flag to False on all attributes and changes the record state to Queried_Record
Procedure Clear_Dirty (Record, Name)	Changes the record attribute dirty flag to False.
ProcedureClear_Record	Clear a record. The complete record is removed from memory.
Function Count_Attributes	Returns number of attributes in a record.
Function Count_Elements	Returns number of elements in a record attribute of type array.
Procedure Debug	Prints the buffer representation of a record
Procedure Debug_Item_Record	Prints an item record
Procedure Debug_Record	Prints a record
Function From_XML	Deserialize record from an XML document.
Function Get_Attribute (Record, Position)	Returns a record attribute by position.
Function Get_Attribute (Record, Name)	Returns a record attribute by name.
Function Get_Binary_Value	Returns a record attribute value as BLOB.
Function Get_Blob_Value (Record, Name)	Returns a record attribute value as BLOB.
Function Get_Clob_Value	Returns a record attribute value as CLOB.
Function Get_Domain	Returns domain value from a Reference or Key attribute.
Function Get_Element	Returns a record element from an array of attributes by element position.
Function Get_Item_Value (Record, Name)	Returns a record attribute value, but ignores exception.
Function Get_Long_Text_Value (Record, Name)	Returns a record attribute value as CLOB.
Function Get_Name (Record)	Returns a record name.
Function Get_Name	Returns a record attribute name.
Function Get_Next_Element	Returns next record element from an array of attributes.
Function Get_Record_Attr (Record)	Converts a record to attribute string.
Function Get_Status (Record)	Returns the record state.
Function Get_Status	Returns a record attribute state. (See Is_Dirty)
Function Get_Type (Record)	Returns a record type.
Function Get_Type	Returns a record attribute type.
Function Get_Value	Returns a record attribute value as VARCHAR2.
Function Is_Dirty (Record, Name)	Returns True if record attribute is dirty otherwise False.
Procedure Make_Dirty (Record, Name)	Changes a record attribute state to dirty (Modified).
Function New_Record(Name, Status)	Creates a Record
Procedure Set_Blob_Value	Set a value on a record attribute.
Procedure Set_Clob_Value	Set a value on a record attribute. Same as Set_Value with CLOB.
Procedure Set_Domain (Record)	Set the domain value on every key-attribute and every not-null reference-attribute in the record.
Procedure Set_Domain (Record, Name)	Set the domain value on a record key- or reference-attribute.
Procedure Set_New (Record)	Set the record state to New_Record
Procedure Set_Queried (Record)	Set the record state to Querid_Record
Procedure Set_Removed (Record)	Set the record state to Removed_Record
Procedure Set_Value	Set a value on a record attribute
Function To_XML	Serialize a record to XML document (up to 32 kB)
Procedure To_Xml	Serialize a record to XML document

Example

PROCEDURE Send_Application_Message_rec (  
   sender_          VARCHAR2,  
   message_type_    VARCHAR2,  
   address_data_    VARCHAR2,  
   sent_            VARCHAR2) IS  
   AM           Plsqlap_Record_API.type_record_;  
   AL           Plsqlap_Record_API.type_record_;  
   AL1          Plsqlap_Record_API.type_record_;  
   AL2          Plsqlap_Record_API.type_record_;  
   AL4          Plsqlap_Record_API.type_record_;  
   TB           Plsqlap_Record_API.type_record_;  
   Domain_      Plsqlap_Record_API.type_buffer_;  
   cnt_         NUMBER;  
   sent_date_   DATE;  
BEGIN  
   AM  := Plsqlap_Record_API.New_record('APPLICATION_MESSAGE');  
   AL  := Plsqlap_Record_API.New_record('ADDRESS_LABEL');  
   AL1 := Plsqlap_Record_API.New_record('ADDRESS_LABEL');  
   AL2 := Plsqlap_Record_API.New_record('ADDRESS_LABEL');  
   TB  := Plsqlap_Record_API.New_record('TEXT_BODY');  

   Plsqlap_Record_API.Set_Value(AM,'APPLICATION_MESSAGE_ID','100',Plsqlap_Record_API.dt_Text_Key,FALSE);  
   Plsqlap_Record_API.Set_Value(AM,'SENDER',sender_,Plsqlap_Record_API.dt_Text);  
   Plsqlap_Record_API.Set_Value(AM,'MESSAGE_TYPE',message_type_,Plsqlap_Record_API.dt_Text);  

   Plsqlap_Record_API.Set_Value(AL,'TRANSPORT_CONNECTOR','Mail',Plsqlap_Record_API.dt_Text);  
   Plsqlap_Record_API.Set_Value(AL,'ADDRESS_DATA',address_data_,type_ => Plsqlap_Record_API.dt_Text);  
   Plsqlap_Record_API.Set_Value(AL,'SENT',sent_,Plsqlap_Record_API.dt_Date);  

   Plsqlap_Record_API.Set_Value(AL1,'TRANSPORT_CONNECTOR','Mail',Plsqlap_Record_API.dt_Text);  
   Plsqlap_Record_API.Set_Value(AL1,'ADDRESS_DATA','Olle',type_ => Plsqlap_Record_API.dt_Text);  
   Plsqlap_Record_API.Set_Value(AL1,'SENT',sent_,Plsqlap_Record_API.dt_Date);  

   Plsqlap_Record_API.Set_Value(TB,'TEXT_VALUE','This is the message body',Plsqlap_Record_API.dt_Long_Text);  

   Plsqlap_Record_API.Add_Array(AM,'ADDRESS_LABEL_LIST',AL);  
   Plsqlap_Record_API.Add_Array(AM,'ADDRESS_LABEL_LIST',AL1);  
   Plsqlap_Record_API.Add_Aggregate(AM,'TEXT_BODY',TB);  

   Plsqlap_Server_API.Invoke_Record_Impersonate('Utility_Application_Messaging','Route_Message',AM);  

   -----------------  
   -- STATISTICS: --  
   -----------------  
   -- See the contents of the whole record  
   Plsqlap_Record_API.Debug(AM);  

   -- Count_Attributes(Record)  
   dbms_output.put_line(to_char(Plsqlap_Record_API.Count_Attributes(AM)));  

   -- Count_Elements(Record,Element)  
   dbms_output.put_line(to_char(Plsqlap_Record_API.Count_Elements(AM,'ADDRESS_LABEL_LIST')));  
   dbms_output.put_line(to_char(Plsqlap_Record_API.Count_Elements(AM,'TEXT_BODY')));  

   -- Get_Status(Record)  
   dbms_output.put_line(Plsqlap_Record_API.Get_Status(AM));  

   -- Get_Status(Record,Attribute)  
   dbms_output.put_line(nvl(Plsqlap_Record_API.Get_Status(AM,'APPLICATION_MESSAGE_ID'),'Queried'));  

   -- Get_Domain (Record,Attribute)  
   dbms_output.put_line(Plsqlap_Record_API.Get_Domain(AM,'APPLICATION_MESSAGE_ID'));  

   -- Get_Type(Record,Attribute)  
   dbms_output.put_line(Plsqlap_Record_API.Get_Type(AM,'APPLICATION_MESSAGE_ID'));  

   -- Get_Type(Record,Element)  
   AL2 := Plsqlap_Record_API.Get_Element(AM,'ADDRESS_LABEL_LIST',2);  
   dbms_output.put_line(Plsqlap_Record_API.Get_Type(AL2,'SENT'));  

   -- Get_Value(Record,Element)  
   sent_date_ := to_date(Plsqlap_Record_API.Get_Value(AL2,'SENT'),'yyyy-mm-dd-hh24:mi:ss');  
   dbms_output.put_line(to_char(sent_date_,'yyyy-mm-dd-hh24:mi:ss');  

   -- Get_Status(Record,Element)  
   dbms_output.put_line(Plsqlap_Record_API.Get_Status(AL2,'SENT'));  

   -- Clear_Dirty(Record)  
   Plsqlap_Record_API.Clear_Dirty(AM);  

   -- Change Value  
   AL4 := Plsqlap_Record_API.Get_Element(AM,'ADDRESS_LABEL_LIST',4);  
   Plsqlap_Record_API.Set_Value(AL4,'ADDRESS_DATA','New_Addressee',Plsqlap_Record_API.dt_Text);  

   -- Plsqlap_Record_API.Add_Array(AM,'ADDRESS_LABEL_LIST',AL4);  
   -- NOT ALLOWED, already exists!  

   -- Invoke Record and Debug for instance...  
   Plsqlap_Server_API.Invoke_Record_Impersonate('Utility_Application_Messaging','Route_Message',AM);  

   Plsqlap_Record_API.Debug(AM);  
   Plsqlap_Record_API.Clear_Record(AM);  
END Send_Application_Message_rec;