You are here: Function Reference > Alphabetical Listing > A > AppendTxmUnique

AppendTxmUnique

Use this procedure/function to append text into a multiline field from an external text area. This procedure also renames the fields imported from the external text area so they have unique names. You can use this procedure in these specific situations:

This procedure lets you import paragraphs with embedded fields, when you know that those fields should never inherit data from the existing section and you expect the user to tab through the imported field and enter new data.
This procedure lets you import the same section multiple times and have the field data for each instance uniquely named.

Note

When it renames fields, this procedure makes sure the field names are unique for the entire form, not just the section that contains the text area. This prevents naming conflicts with prior sections.

This procedure only works on multiline text fields.

Syntax

AppendTxmUnique (FAP, InsertFld, Field, Section, Form, Group)

Parameter	Description
FAP	Enter the name of a section file that contain a text area. This text area is appended to the field specified. If there are several text areas in the section file, the system grabs the text from the first text area it finds. If you omit the path, the system looks for the form in the forms directory specified using the File, Library Setup option.
InsertFld	Enter the name of a field before which you want the embedded fields in the imported text area inserted. The default is to append after the last field in the section.
Field	Enter the name of the field that identifies a multiline text area. This is the field that receives the appended text. The default is the current field.
Section	Enter the name of a section that contains the field. The default is the current section.
Form	Enter the name of a form that contains the section and/or field. The default is the current form.
Group	Enter the name of the group that contains the form, section, and/or field. The default is the current group.

The system optionally returns a one (1) if successful and zero (0) if unsuccessful.

This procedure opens the section and appends the text from the first text area field found in that section. If successful, the new text will be formatted appropriately in the destination field.

The system locates the section in the directory where sections (FAP files) are typically found. Use the Refresh procedure to make sure all appended text appears in the field.

This procedure is similar to the AppendTxm procedure. For instance, suppose your paragraph section looks like this, where X1 is a reference to the Name field and X2 is a reference to the City field.

X1 of X2. X1 please let me know if you received this by mistake.

The Name field is embedded twice and the City field once. If you were to use the AppendTxm procedure on this section three times, the result would look like this:

X1 of X2. X1 let me know if you received this by mistake.

However, there would be only one Name and City field defined on the section. If you set Name to Tom and City to Marietta, the paragraph would look like this.

Tom of Marietta. Tom let me know if you receive this by mistake.

Using the AppendTxmUnique procedure, if you append this section three times, the first line would likely still reference Name and City (it would depend upon whether there was already a field named Name or City on the section).

The second occurrence however, would be renamed to NAME #002 and CITY #002. The third occurrence would be renamed to NAME #003 and CITY #003.

So, instead of two fields, you now have six fields to tab through and each subsequent occurrence can hold a different value.

Tom of Marietta. Tom let me know if you receive this by mistake.

John of Athens. John let me know if you receive this by mistake.

Albert of Atlanta. Albert let me know if you receive this by mistake.

Notice that multiple references to the same field in a paragraph still associate to the same field. So although there are three embedded locations in each paragraph, there are only two separate fields being referenced.

Field Renaming for Entire Form

This procedure renames the field uniquely for the entire form, not just the section that contains the multiline text field. This occurs because a multiline text field can span pages and you don’t want the field names to duplicate.

For instance, suppose you have a paragraph with one embedded field. The first time you append it, it is named Field (assuming field is the original name and does not conflict. Each time you append it you get a unique name:

FIELD #002

FIELD #003

and so on...

Eventually, an AppendTxmUnique procedure could cause a the text to overflow to a new page. Let’s assume you were up to FIELD #010 when that occurred.

If you run the AppendTxmUnique procedure again, the name FIELD does not occur on the second page, but it did on the first. You want FIELD #011 to be next. This is why the names unique at the form level and not the section level.

Example

Here are some examples:

Procedure	Result	Explanation
#rc = AppendTxmUnique ("message", , "name_line"); Refresh ( );	1 if successful, 0 if not.	The first text area in the Message FAP file is appended to the Name_line multiline text field.
#rc = AppendTxmUnique (".\mstrres\messages\msg1", , "name_line", "mailer"); Refresh ( );	1 if successful, 0 if not.	The first text area in the MSG1 FAP file located in the \mstrres\message\ directory is appended to the Name_line multiline text field, which is in the Mailer FAP file.
#rc = AppendTxmUnique ("message", "address1" , "name_line"); Refresh ( );	1 if successful, 0 if not.	The first text area in the Message FAP file is appended to the Name_line multiline text field. Any embedded variable fields in the text area are inserted before the Address1 variable field, based on the tabbing sequence.

AppendTxmUnique

Syntax

Field Renaming for Entire Form

Example

See also