SaveTextJournal

Creates a new journal, or saves changes to an existing journal that has a Working or Submitted status.

Caution!

To successfully call SaveTextJournal, the connected user must be assigned to the Journals Administrator or Create Journals role, and must have All access to the journal’s security class.

The arguments for journal line items consist of arrays. The arrays have a one-to-one correspondence; for example, the second elements in the varabstrAmount and vararlAccount arguments’ arrays specify the amount and account for a journal’s second line item.

SaveTextJournal is almost identical to SaveJournal; the only difference is that SaveTextJournal passes line item amounts in a String array while SaveJournal passes line item amounts in a Double array. For more information, see SaveJournal.

Tip:	To create a journal from a template, use GetTextTemplate to get the template’s information, then pass the applicable GetTextTemplate return values to SaveTextJournal. For information on GetTextTemplate, see GetTextTemplate.

Syntax

<IHsvJournalsEx>.SaveTextJournal lScenario, lYear, lPeriod, lValue, nType, nStatus, nAttribute, bstrLabel, bstrDescription, bstrGroup, lSingleEntity, lSingleParent, lSecurityClass, vararnDebitCreditUnit, varabstrAmount, vararbstrDescription, vararlEntity, vararlParent, vararlAccount, vararlICP, vararlCustom1, vararlCustom2, vararlCustom3, vararlCustom4, plJournalID

Argument	Description
lScenario	Long (ByVal). The member ID of the Scenario dimension member.
lYear	Long (ByVal). The member ID of the Year dimension member.
lPeriod	Long (ByVal). The member ID of the Period dimension member.
lValue	Long (ByVal). The member ID of the Value dimension member for the journal’s currency.
nType	Integer (ByVal). Specifies the journal’s type. Pass one of the HFMConstants type library constants listed in Journal Type Constants. Note: You cannot use this method to save journals of type JTF_AUTOREVERSAL, as these are system-generated journals. Attempting to save a journal as this type will throw error number 8004041A (hexadecimal).
nStatus	Integer (ByVal). Specifies the journal’s status. Pass one of the HFMConstants type library constants listed in Journal Status Constants.
nAttribute	Integer (ByVal). Specifies whether the journal must be balanced. Pass one of the Balance Type Constants.
bstrLabel	String (ByVal). The label of the journal.
bstrDescription	String (ByVal). The description of the journal. You can pass a blank string if there is no description.
bstrGroup	String (ByVal). The journal group to which the journal is assigned. You can pass a blank string if the journal is not being assigned to a journal group.
lSingleEntity	Long (ByVal). For single entity journals, specify the member ID of the journal’s base entity. For multi-entity journals, pass a value of -1.
lSingleParent	Long (ByVal). For single entity journals, specify the member ID of the journal’s parent entity. For multi-entity journals, pass a value of -1.
lSecurityClass	Long (ByVal). The ID of the journal’s security class. To get this ID, pass the security class name to HsvSecurityAccess.GetSecurityClassID. For more information, see GetSecurityClassID.
vararnDebitCreditUnit	Integer array (ByVal). Specifies whether the line items are debits or credits. Pass one of the HFMConstants type library constants listed in Debit/Credit Constants.
varabstrAmount	String array (ByVal). The amounts of the line items.
vararbstrDescription	String array (ByVal). The descriptions of the line items.
vararlEntity	Long array (ByVal). The member IDs for the base entities of the line items. For single-entity items, set the IDs in this array to the same member ID that is in the lSingleEntity argument.
vararlParent	Long array (ByVal). The member IDs for the parent entities of the line items. For single-entity items, set the IDs in this array to the same member ID that is in the lSingleParent argument.
vararlAccount	Long array (ByVal). The member IDs of the accounts for the line items.
vararlICP	Long array (ByVal). The member IDs of the line items’ Intercompany Partner dimension members.
vararlCustom1	Long array (ByVal). The member IDs of the line items’ Custom 1 dimension members.
vararlCustom2	Long array (ByVal). The member IDs of the line items’ Custom 2 dimension members.
vararlCustom3	Long array (ByVal). The member IDs of the line items’ Custom 3 dimension members.
vararlCustom4	Long array (ByVal). The member IDs of the line items’ Custom 4 dimension members.
plJournalID	Long. The purpose of this argument depends upon whether you are creating a new journal or updating an existing journal: For a newly created journal, this argument returns the automatically-generated ID of the journal. To update an existing journal, pass the journal’s ID with this argument. You can get journal IDs with GetItemID; for details, see GetItemID.

Example

This example uses SaveTextJournal in a custom function that creates journals from a template. The custom function is named CreateTextJournal, and takes the following items as arguments:

The member IDs of the applicable Scenario, Year, Period, and Value dimension members.
The name of the template to be used.
The name to be assigned to the journal.
An array of the line item amounts, and a corresponding array that flags the line items as debits or credits.

The example gets the template’s information with GetTextTemplate; note how most of GetTextTemplate’s return values are passed to SaveTextJournal. (More details on the example are provided in the comments.)

Function CreateTextJournal(lScenID As Long, lYearID _
   As Long, lPerID As Long, lValID As Long, _
   sTemplate As String, sJnlName As String, _
   saAmount() As String, iaDebCredUnit() As Integer) As Long
Dim cHsvJournals As HsvJournals
Dim cIHsvJournalEx As IHsvJournalsEx
'Variables for GetTextTemplate - many are also passed to
'SaveTextJournal.
Dim lTempID As Long, iType As Integer, iAttr As Integer
Dim sLabel As String, sDescHead As String, sGroup As String
Dim lSecID As Long, lSingleEnt As Long, lSinglePar As Long
Dim iTempType As Integer, lTempVal As Long, vaEntryIDs
Dim vaDebCredUnit, vaAmt, vaItemDesc, vaEnt, vaPar, vaAcct
Dim vaICP, vaCust1, vaCust2, vaCust3, vaCust4
'Variables for SaveTextJournal
Dim lSecClass As Long, lJnlID As Long
'm_cSession is an HsvSession object reference
Set cHsvJournals = m_cSession.Journals
'Set IHsvJournalsEx object reference
Set cIHsvJournalEx = m_cSession.Journals
'Get the template's ID
lTempID = cHsvJournals.GetJournalTemplateItemID(sTemplate)
'Get the template's data
cIHsvJournalEx.GetTextTemplate lTempID, iType, iAttr, sLabel, _
   sDescHead, sGroup, lSecID, lSingleEnt, lSinglePar, _
   iTempType, lTempVal, vaEntryIDs, vaDebCredUnit, vaAmt, _
   vaItemDesc, vaEnt, vaPar, vaAcct, vaICP, vaCust1, vaCust2, _
   vaCust3, vaCust4
'Create the journal.
cIHsvJournalEx.SaveTextJournal lScenID, lYearID, lPerID, _
   lValID, iType, 1, iAttr, sJnlName, "", "", lSingleEnt, _
   lSinglePar, lSecID, iaDebCredUnit, saAmount, vaItemDesc, _
   vaEnt, vaPar, vaAcct, vaICP, vaCust1, vaCust2, vaCust3, _
   vaCust4, lJnlID
'Assign the return value
CreateTextJournal = lJnlID
End Function