Using the File Outbound Adapter
This topic describes how to use the file outbound adapter (EnsLib.File.OutboundAdapterOpens in a new tab).
InterSystems IRIS® data platform also provides specialized business service classes that use this adapter, and one of those might be suitable for your needs. If so, no programming would be needed. See Business Host Classes That Use File Adapters.
Overall Behavior
Within a production, an outbound adapter is associated with a business operation that you create and configure. The business operation receives a message from within the production, looks up the message type, and executes the appropriate method. This method usually executes methods of the associated adapter.
Creating a Business Operation to Use the Adapter
To create a business operation to use EnsLib.File.OutboundAdapterOpens in a new tab, you create a new business operation class. Later, add it to your production and configure it.
You must also create appropriate message classes, if none yet exist. See Defining Messages.
The following list describes the basic requirements of the business operation class:
-
Your business operation class should extend Ens.BusinessOperationOpens in a new tab.
-
In your class, the ADAPTER parameter should equal EnsLib.File.OutboundAdapterOpens in a new tab.
-
In your class, the INVOCATION parameter should specify the invocation style you want to use, which must be one of the following.
-
Queue means the message is created within one background job and placed on a queue, at which time the original job is released. Later, when the message is processed, a different background job is allocated for the task. This is the most common setting.
-
InProc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be released to the sender’s pool until the message is delivered to the target. This is only suitable for special cases.
-
-
Your class should define a message map that includes at least one entry. A message map is an XData block entry that has the following structure:
XData MessageMap { <MapItems> <MapItem MessageType="messageclass"> <Method>methodname</Method> </MapItem> ... </MapItems> }
-
Your class should define all the methods named in the message map. These methods are known as message handlers. Each message handler should have the following signature:
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class. In general, the method code will refer to properties and methods of the Adapter property of your business operation.
For information on defining message classes, see Defining Messages.
For information on defining the message handler methods, see Creating Message Handler Methods.
-
For other options and general information, see Defining a Business Operation Class.
The following example shows the general structure that you need:
Class EHTP.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.File.OutboundAdapter";
Parameter INVOCATION = "Queue";
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
{
Quit $$$ERROR($$$NotImplemented)
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="RequestClass">
<Method>Sample</Method>
</MapItem>
</MapItems>
}
}
Creating Message Handler Methods
When you create a business operation class for use with EnsLib.File.OutboundAdapterOpens in a new tab, typically your biggest task is writing message handlers for use with this adapter, that is, methods that receive production messages and then write files.
Each message handler method should have the following signature:
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class.
In general, the method should do the following:
-
Examine the inbound request message.
-
Using the information from the inbound request, call a method of the Adapter property of your business operation. The following example calls the EnsLib.File.OutboundAdapterOpens in a new tab method PutString():
/// Send an approval to the output file Method FileSendReply(pRequest As Demo.Loan.Msg.SendReply, Output pResponse As Ens.Response) As %Status { $$$TRACE("write to file "_pRequest.Destination) Set tSC=..Adapter.PutString(pRequest.Destination, pRequest.Text) Quit tSC }
You can use similar syntax to call any of the EnsLib.File.OutboundAdapterOpens in a new tab methods described in Calling Adapter Methods from the Business Operation.
-
Make sure that you set the output argument (pOutput). Typically you set this equal to the response message. This step is required.
-
Return an appropriate status. This step is required.
Calling Adapter Methods from the Business Operation
Your business operation class can use the following instance methods of EnsLib.File.OutboundAdapterOpens in a new tab.
ClassMethod CreateTimestamp(pFilename As %String = "",
pSpec As %String = "_%C") As %String
Using the pFilename string as a starting point, incorporate the time stamp specifier provided in pSpec and return the resulting string. The default time stamp specifier is _%C which provides the full date and time down to the millisecond.
For full details about time stamp conventions, see Time Stamp Specifications for Filenames.
Method Delete(pFilename As %String) As %Status
Deletes the file.
Method Exists(pFilename As %String) As %Boolean
Returns 1 (True) if the file exists, 0 (False) if it does not.
Method GetStream(pFilename As %String,
ByRef pStream As %AbstractStream = {$$$NULLOREF})
As %Status
Gets a stream from the file.
Method NameList(Output pFileList As %ListOfDataTypes,
pWildcards As %String = "*",
pIncludeDirs As %Boolean = 0) As %Status
Get a list of files in the directory specified by the FilePath setting. The filenames are returned in a %ListOfDataTypesOpens in a new tab object. Each entry in the list is a semicolon-separated string containing:
Filename;Type;Size;DateCreated;DateModified;FullPathName
Method PutLine(pFilename As %String, pLine As %String) As %Status
Writes a string to the file and appends to the string the characters specified in the LineTerminator property. By default, the LineTerminator is a carriage return followed by a line feed (ASCII 13, ASCII 10).
If your operating system requires a different value for the LineTerminator property, set the value in the OnInit() method of the business operation. For example:
Method OnInit() As %Status
{
Set ..Adapter.LineTerminator="$C(10)"
Quit $$$OK
}
You can also make the property value to be dependent on the operating system:
Set ..Adapter.LineTerminator="$Select($$$isUNIX:$C(10),1:$C(13,10))"
Method PutString(pFilename As %String, pData As %String) As %Status
Writes a string to the file.
Method PutStream(pFilename As %String,
pStream As %Stream,
ByRef pLen As %Integer = -1) As %Status
Writes a stream to the file.
Method Rename(pFilename As %String,
pNewFilename As %String,
pNewPath As %String = "") As %Status
Renames the file in the current path or moves it to the path specified by pNewPath.
Example Business Operation Class
The following code example shows a business operation class that references the EnsLib.File.OutboundAdapterOpens in a new tab. This class can perform two operations: If it receives valid Person data, it files Person information based on Person status. If it receives invalid Person data, it logs this information separately.
Class training.operation.OpeFilePerson extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.File.OutboundAdapter";
Parameter INVOCATION = "Queue";
/* write on log file wrong person records */
Method writeMessage(
pRequest As MyData.Message,
Output pResponse As Ens.StringResponse)
As %Status
{
$$$LOGINFO("called Writer")
set ..Adapter.FilePath="C:\InterSystems\test\ftp"
set st=..Adapter.PutLine("person.log",message)
Quit $$$OK
}
/* write on log file wrong person records */
Method logWrongPerson(
pRequest As training.healthcare.message.MsgPerson,
Output pResponse As Ens.StringResponse)
As %Status
{
$$$LOGINFO("called OpeFilePerson")
set ..Adapter.FilePath="C:\InterSystems\test\errorparh"
set message="some information are missing from record: " _
pRequest.sso _ ", " _
pRequest.name _ ", " _
pRequest.surname
set st=..Adapter.PutLine("Person.log",message)
Quit $$$OK
}
/* write in xml format the list of active/inactive/requested Persons */
Method writeSSOList(
pRequest As Ens.StringRequest,
Output pResponse As Ens.StringResponse)
As %Status
{
set ..Adapter.FilePath="C:\InterSystems\test\ftp"
set status=pRequest.StringValue
if status="ACTIVE" set fileName="ActiveSSO.xml"
if status="INACTIVE" set fileName="InactiveSSO.xml"
if status="REQUESTED" set fileName="RequestedSSO.xml"
set st=..Adapter.PutLine(fileName,"<Persons>")
set rs=
##class(training.healthcare.data.TabPerson).selectPersons("",status)
while rs.Next(){
set st=..Adapter.PutLine(fileName,"<Person>")
for i=1:1:rs.GetColumnCount() {
set st=..Adapter.PutLine(fileName,
"<"_ rs.GetColumnName(i)_">" _
rs.GetData(i)_"</"_ rs.GetColumnName(i)_">")
}
set st=..Adapter.PutLine(fileName,"<Person>")
}
set st=..Adapter.PutLine(fileName,"<Persons>")
set pResponse=##class(Ens.StringResponse).%New()
set pResponse.StringValue="done"
quit $$$OK
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="training.healthcare.message.MsgPerson">
<Method>logWrongPerson</Method>
</MapItem>
<MapItem MessageType="Ens.StringRequest">
<Method>writeSSOList</Method>
</MapItem>
</MapItems>
}
}
Adding and Configuring the Business Operation
To add your business operation to a production, use the Management Portal to do the following:
-
Add an instance of your business operation class to the production.
-
Configure the business operation. For information on the settings, see Settings for the File Outbound Adapter.
-
Enable the business operation.
-
Run the production.