#

*OBJ/WORD | PxPlus Word Object

The PxPlus Word object simplifies the use of the Word.Application extended object. This object consists of various properties and methods that make it easier to interact with Word documents. See Properties and Methods.

The Word object allows more than one Word document to be opened at one time.

(The PxPlus Word object was added in PxPlus 2017.)

Instantiating the Word Object

To instantiate the Word object using the handle word_obj (where word_obj could be any numeric variable), enter the following command:

> word_obj=NEW("*obj/word")

If the object should bind to a running instance of Word, you may pass the [RUNNING] option for the DEF_OBJECT directive by entering the command as:

> word_obj=NEW("*obj/word","running")

> Where:

> "running" is case insensitive.

(The ability to instantiate the Word object by passing the [RUNNING] parameter was added in PxPlus 2025.)

If the object should bind to a running instance of Word, if possible, but create a new instance otherwise, you may pass the [RUNNING OR NEW] option for the DEF_OBJECT directive by entering the command as:

> word_obj=NEW("*obj/word","running or new")

> Where:

> "running or new" is case insensitive.

(The ability to instantiate the Word object by passing the [RUNNING OR NEW] parameter was added in PxPlus 2025.)

To access any of the available properties and/or methods, the Word object handle (word_obj) is used, followed by an ' (apostrophe) and the property or method (with the desired parameters).

Examples:

> doc=word_obj'ACTIVE_DOCUMENT
> retVal=word_obj'SetDocument(3)

#### Note:
If you are familiar with the Word.Application extended object, all existing properties and methods will continue to be accessible by referencing the WORD property.
Example:
C=word_obj'WORD'DOCUMENTS'Count

When an Error is Encountered

In case of method failure, the ERROR object may be useful in getting more information about the last error encountered.

Example:

If Word is unable to set the active document in the previous example because there are not three documents in the collection, retVal will be equal to '0'. Checking the Description$ property of the ERROR object may also provide more information:

> PRINT word_obj'ERROR'Description$
> The requested member of the collection does not exist.

Global Named Constants

The Word Application makes use of hundreds of global named constants. If required, these constants may be accessed by using the PVXCONSTANTS object, which has been defined as a property called WCONSTANTS. See *CONSTANTS.

Example:

> PRINT word_obj'WCONSTANTS'wdAlertsMessageBox (should return -2)

## Properties and Methods

The properties used by the Word object are listed below.

Property | Description
ACTIVE_DOCUMENT | (Read Only) Handle to the active document object. This property is set by using the SetDocument method and corresponds to the WORD'ActiveDocument value.
CASE_SENSITIVE_SEARCH | Defaults to '0' for case insensitive searches. Set to '1' for case sensitive searches. See Find, FindInsert, FindReplace, FindReplaceAll, FindSetColor and FindSetFont methods below.
DISPLAY_ALERTS | Allows suppression of Word message boxes. Defaults to Off ('0').
DOCUMENTS_COUNT | (Read Only) Number of documents opened. This property corresponds to the WORD'DOCUMENTS'Count value.
ERROR | (Read Only) Handle to Word ERROR object. Can be used to display the last error message via the Description$ property.
INSERT_BEFORE | Defaults to '0' so that the Insert (see FindInsert below) will insert text after the position located with the Find method. To insert text before the position located with the Find method, set this value to '1'.
KEEP_VISIBLE | Set to a non-zero value to keep the Word application active and visible when the PxPlus Word Object is dropped. Has no effect if the VISIBLE property has not been set. Defaults to Off ("0"). (The KEEP_VISIBLE property was added in PxPlus 2020.)
SEARCH_FORWARD | Defaults to '1' so that the FindReplaceAll and the various Find methods (see Find, FindInsert, FindReplace, FindSetColor and FindSetFont) will search from the beginning of the document to the end. To begin at the end of the document (i.e. find the last occurrence of a string), set this value to '0'.
VISIBLE | Allows the Word application to be made visible. Defaults to Off ('0').
WCONSTANTS | (Read Only) Handle to the Word CONSTANTS object.
WORD | (Read Only) Handle to the main Word object. #### Note: This property cannot be set but is provided to allow access to all of the properties and methods in the Word Application.

The methods used by the Word object are listed below. To make it easier to locate information for a particular method, this list has been broken into the following smaller groups:

| Document Methods | For creating, setting, printing, saving and closing a document
| Paragraph Methods | For creating, inserting, reading and deleting a paragraph
| Sentence Methods | For creating, inserting, reading and deleting a sentence
| Text Methods | For finding, replacing, inserting and setting text color/font

Common Parameters

The following is a list of some of the common parameters used by multiple methods of the Word object:

Parameter | Description
document | 1-based index number of the Word document.
document_name$ | Simple document name without the full path (e.g. "test_document.docx").
path$ or document_path$ | Full path name for the document (e.g. "c:/application/test_document.docx").

Document Methods

Document Methods | Description
AppendFile(path$) AppendFile(path$,document) AppendFile(path$,document_name$) | Appends the file defined as path$ at the end of the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the file indicated by path$ is invalid. (The AppendFile method was added in PxPlus 2019.)
CloseDocument( ) CloseDocument(document) CloseDocument(document_name$) | Closes the document specified by either an index number or a simple document name. If no document is specified, the active document will be closed. #### Note: Any unsaved changes in a document are not saved if the DISPLAY_ALERTS property is set to '0' (zero), the default value. To prompt the user about saving the changes, set DISPLAY_ALERTS to '1'. To ensure that all changes are saved and minimize user intervention, be sure to save the document prior to closing. Returns '1' if successful. Returns '0' if Word was unable to locate or close the document.
CloseDocuments( ) | Closes all open documents. This method is called automatically when the Word object is dropped. #### Note: Any unsaved changes in the documents are not saved if the DISPLAY_ALERTS property is set to '0' (zero), the default value. To prompt the user about saving the changes, set DISPLAY_ALERTS to '1'. To ensure that all changes are saved and minimize user intervention, be sure to save the documents prior to closing. Returns '1' if successful. Returns '0' if Word was unable to close the documents.
CreateDocument(path$) | Creates a new Word document (path$). The path$ parameter may be either a simple or full pathname. The new document is opened and becomes the ACTIVE_DOCUMENT. If the path$ parameter is null, the document is named according to the Word default (e.g. Document1.docx). #### Warning! In case of a pre-existing file named path$, the previous version will be overwritten with no prompt to the user. Returns '1' if successful. Returns '0' if Word was unable to add the document.
InsertFile(path$) InsertFile(path$,para_num) InsertFile(path$,para_num,document) InsertFile(path$,para_num,document_name$) | Allows you to merge two files together by inserting a specified file into a given location (paragraph number) in a particular document. Inserts the file defined as path$ in the document specified by either an index number or a simple document name. The file will be inserted beginning as paragraph number para_num. If no document is specified, the active document is assumed. If para_num is not specified or is set to 0, the file will be inserted beginning at paragraph 1. If para_num is larger than the current number of paragraphs, the paragraph will be inserted before the last paragraph. Alternatively, to insert a file at the very end of the document, use one of the AppendFile( ) methods. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the file indicated by path$ is invalid. (The InsertFile method was added in PxPlus 2019.)
OpenDocument(path$) | Opens the Word document located at pathname path$. After opening a document, the ACTIVE_DOCUMENT property is set to the document object corresponding to the document just opened. #### Note: When opening more than one document, the last document opened is always considered to be document index 1. All of the previously opened document indexes move up one index higher. Returns '1' if successful. Returns '0' if the path specified was invalid or if Word was unable to open the document.
PrintDocument( ) PrintDocument(document) PrintDocument(document_name$) | Prints the document specified by either an index number or a simple document name. If no document is specified, the active document is printed. To print all of the documents currently opened, pass a document_name$ of 'ALL' (case insensitive). #### Note: No printer dialog will be displayed. The document will be printed to the default Word printer with the default settings. Returns '1' if successful. Returns '0' if Word was unable to locate the document.
SaveAsDocument(document_path$) SaveAsDocument(document_path$,document) SaveAsDocument(document_path$,document_name$) | Used to save a document to a different location or with a different file format. Saves the document specified (by either an index number or a simple document name) with the pathname provided. If no document is specified, the active document is saved. If a full pathname is not provided, the document will be saved in the default Word document folder. The format used to save the document is determined by the extension specified in the document_path$. Supported extensions are listed below (in alphabetical order).
| .doc | Word 97 - 2003 Document | .mht, .mhtml | Single File Web Page
| .docm | Word Macro-Enabled Document | .odt | Open Document Text
| .docx (or null) | Word Document | .pdf | PDF
| .dot | Word 97 – 2003 Template | .rtf | Rich Text Format
| .dotm | Word Macro-Enabled Template | .txt | Plain Text (preserve line breaks)
| .dotx | Word Template | .xml | Word XML Document
| .htm, .html | Web Page | .xps | XPS Document
Returns '1' if successful. Returns '0' if the pathname is invalid, already exists, or if Word was unable to save the document. (Support for other file formats was added in PxPlus 2018.)
SaveDocuments( ) | Saves all currently opened documents. Returns '1' if successful. Returns '0' if Word was unable to save any of the documents. Returns '-1' if Word was only able to save some of the documents successfully.
SaveDocument( ) SaveDocument(document) SaveDocument(document_name$) | Saves the document specified by either an index number or a simple document name. If no document is specified, the active document is saved. Returns '1' if successful. Returns '0' if Word was unable to locate or save the document.
SetDocument(document) SetDocument(document_name$) | Sets the active document object ACTIVE_DOCUMENT to the document specified by either an index number or a simple document name (e.g. sample_doc.docx). Returns '1' if successful. Returns '0' if Word was unable to locate the document.

Paragraph Methods

Paragraph Methods | Description
AppendParagraph(para_text$) AppendParagraph(para_text$,document) AppendParagraph(para_text$,document_name$) | Appends the text defined as para_text$ as a new paragraph at the end of the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. To insert a paragraph with no text, set para_text$="". Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The AppendParagraph method was added in PxPlus 2019.)
InsertParagraph(para_text$) InsertParagraph(para_text$,para_num) InsertParagraph(para_text$,para_num,document) InsertParagraph(para_text$,para_num,document_name$) | Inserts the text defined as para_text$ as a new paragraph added to the document specified by either an index number or a simple document name. The paragraph will be inserted as paragraph number para_num. If no document is specified, the active document is assumed. If para_num is not specified or is set to 0, the paragraph will be inserted as paragraph 1. If para_num is larger than the current number of paragraphs, the paragraph will be inserted as the last paragraph. Alternatively, to insert a paragraph at the very end of the document, use one of the AppendParagraph( ) methods. To insert a paragraph with no text, set para_text$="". Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The InsertParagraph method was added in PxPlus 2019.)
ReadParagraph$(para_num) ReadParagraph$(para_num,document) ReadParagraph$(para_num,document_name$) | Reads the contents of the paragraph numbered para_num in the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A para_num value of less than 1 will read the first paragraph. Returns a string containing the text for the paragraph specified if successful. Returns '0' if Word was unable to locate the document specified or the paragraph number para_num does not exist. (The ReadParagraph$ method was added in PxPlus 2019.)
DeleteParagraph(para_num) DeleteParagraph(para_num,document) DeleteParagraph(para_num,document_name$) | Deletes the paragraph numbered para_num from the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A para_num value of less than 1 will delete the first paragraph. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the paragraph number para_num does not exist. (The DeleteParagraph method was added in PxPlus 2019.)

Sentence Methods

Sentence Methods | Description
AppendSentence(sent_text$) AppendSentence(sent_text$,document) AppendSentence(sent_text$,document,name$) | Appends the text defined as sent_text$ as a new sentence (or sentences) at the end of the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The AppendSentence method was added in PxPlus 2019.)
InsertSentence(sent_text$) InsertSentence(sent_text$,sent_num) InsertSentence(sent_text$,sent_num,document) InsertSentence(sent_text$,sent_num,document_name$) | Inserts the text defined as sent_text$ as a new sentence added to the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. If sent_num is set to 0, the sentence will be inserted as sentence 1. If sent_num is larger than the current number of sentences, the sentence will be inserted as the last sentence. Alternatively, to insert a sentence at the very end of the document, use one of the AppendSentence( ) methods. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The InsertSentence method was added in PxPlus 2019.)
ReadSentence$(sent_num) ReadSentence$(sent_num,document) ReadSentence$(sent_num,document_name$) | Reads the contents of the sentence numbered sent_num in the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A sent_num value of less than 1 will read the first sentence. Returns a string containing the text for the sentence specified if successful. Returns '0' if Word was unable to locate the document specified or the sentence number sent_num does not exist. (The ReadSentence$ method was added in PxPlus 2019.)
DeleteSentence(sent_num) DeleteSentence(sent_num,document) DeleteSentence(sent_num,document_name$) | Deletes the sentence numbered sent_num from the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A sent_num value of less than 1 will delete the first sentence. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the sentence number sent_num does not exist. (The DeleteSentence method was added in PxPlus 2019.)

Text Methods

Text Methods | Description
Find(find$) Find(find$,document) Find(find$,document,instance) Find(find$,document_name$) Find(find$,document_name$,instance) | Determines if a particular string (find$) exists in a document specified by either an index number or a simple document name. If no document is specified, the Find will check the active document. Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. Returns '1' if the text find$ was found. Returns '0' if Word was unable to locate the document or if the text find$ was not found in the document.
FindInsert(find$,insert$) FindInsert(find$,insert$,document) FindInsert(find$,insert$,document,instance) FindInsert(find$,insert$,document_name$) FindInsert(find$,insert$,document_name$,instance) | Finds the text defined as find$ in a document specified by either an index number or a simple document name and inserts the text defined as insert$ into the document. If no document is specified, the active document is assumed. To perform the Insert on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. By default, the insert$ text will be inserted immediately following the find$ text. To insert the insert$ text before the find$ text, set the INSERT_BEFORE property to '1'. Returns '1' if successful. Returns '0' if the Find was unsuccessful or if Word was unable to locate the document or insert the text.
FindReplace(find$,replace$) FindReplace(find$,replace$,document) FindReplace(find$,replace$,document,instance) FindReplace(find$,replace$,document_name$) FindReplace(find$,replace$,document_name$,instance) | Finds the text defined as find$ in a document specified by either an index number or a simple document name and replaces the find$ text with the replace$ text. If no document is specified, the active document is assumed. To perform the Replace on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. Returns '1' if successful. Returns '0' if the Find was unsuccessful or if Word was unable to locate the document or replace the text.
FindReplaceAll(find$,replace$) FindReplaceAll(find$,replace$,document) FindReplaceAll(find$,replace$,document_name$) | Finds the string find$ and replaces all occurrences with the string replace$. When only the find$ and replace$ parameters are passed, the Find/Replace is performed on the active document. Pass either a document index number or a simple document name to perform the Find/Replace on a document other than the active document without changing the ACTIVE_DOCUMENT property. To perform the Find/Replace on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. Searches will replace all occurrences of the find$ string. The FindReplace method can be used to replace a single occurrence of the find$ string. Returns '1' if successful. Returns '0' if Word was unable to perform Find/Replace on any of the documents specified or if the find$ value was not found. When finding/replacing on all documents: Returns '-1' if Word was only able to perform find/replace on some of the documents successfully.
FindSetColor(find$,color_index) FindSetColor(find$,color_index,document) FindSetColor(find$,color_index,document,instance) FindSetColor(find$,color_index,document_name$) FindSetColor(find$,color_index,document_name$,instance) FindSetColor(find$,color$) FindSetColor(find$,color$,document) FindSetColor(find$,color$,document,instance) FindSetColor(find$,color$,document_name$) FindSetColor(find$,color$,document_name$,instance) | Finds the text defined as find$ in a document specified by either an index number or a simple document name and sets the color for that text as specified in color_index or color$. If no document is specified, the active document is assumed. To set the color of the find$ text on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. The text color may be passed as one of the following: • A color index (numeric) • An RGB value in the format "RGB(rrr,ggg,bbb)" (string) • A wdColorIndex constant such as "wdColorAqua" (string) • A wdColor constant such as "wdPink" • One of the 16 basic PxPlus named colors such as 'Red', 'Dark Blue' or 'Light Cyan' (string) (RGB values and color constants were added in PxPlus 2019.) #### Note: A Word color index is an integer value ranging from 1 to 16. Returns '1' if successful. Returns '0' if the Find was unsuccessful or if Word was unable to locate the document or set the color.
FindSetFont(find$,font$) FindSetFont(find$,font$,document) FindSetFont(find$,font$,document,instance) FindSetFont(find$,font$,document_name$) FindSetFont(find$,font$,document_name$,instance) | Finds the text defined as find$ in a document specified by either an index number or a simple document name and sets the font information (font name, font size, font style) for that text as specified in font$. If no document is specified, the active document is assumed. To set the font of the find$ text on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. The font$ variable can pass font name, font size and font style (Bold, Italic, etc.), separated by commas. Example: font$="Arial" sets only the font name. font$="Arial,12" sets the font name and size. font$="Arial,12, Italic" sets the font name and size and adds italics to the text in the range. font$="Arial,12, Bold, Underline-" sets the font name and size, adds bolding and removes any underlining. font$="Arial,12, Regular" sets the font name and size and removes any bolding, italics and underlining. #### Note: Valid fontstyle$ values are 'Regular', 'Bold+', 'Bold-', 'Bold' (same as 'Bold+'), 'Italic+', 'Italic-', 'Italic' (same as Italic+), 'Underline+', 'Underline-', 'Underline' (same as 'Underline+') or any combination of these. Returns '1' if successful. Returns '0' if the Find was unsuccessful or if Word was unable to locate the document or set the font. (Support for removing bolding, italics and underlining was added in PxPlus 2021.)

## Example 1: Testing the Word Object

This example tests the Word object.

> ! Test word object
> !
> ! Instantiate object
> w=NEW("*obj/word")
> !
> ! Open document
> path$="c:\documents\document1.docx"
> doc1=w'OpenDocument(path$)
> !
> ! Open another document
> path2$="c:\documents\document2.docx"
> doc2=w'openDocument(path2$)
> !
> ! Check number of documents open
> MSGBOX STR(w'documents_count)
> !
> ! Set document to first document opened
> t=w'SetDocument("document2.docx)
> !
> ! Search and Replace on all opened documents
> find$="[FirstName]"
> replace$=firstName$
> test=w'FindReplaceAll(find$,replace$,"all")
> !
> ! Make Word visible
> w'Visible=1
> !
> ! Set active document
> q=w'SetDocument(2)
> !
> ! find text and set font in active document
> w'FindSetFont("Set font on this text","Algerian,18,bold")
> !
> ! find second instance of text and set color index of active document
> w'FindSetColor("Sample text",4,0,2)
> !
> ! Find last instance of text and replace with alternate text in test.docx
> w'search_forward=0
> w'FindReplace("Find Text","Replace text","test.docx",1)
> !
> ! Save active document with another name
> w'SaveAsDocument("c:\document\differentdoc.docx")
> !
> !
> DROP OBJECT w
> END

## Example 2: Using the Word Object in a Template

This example demonstrates using the Word object to replace given placeholders in a template document with variable data:

- The promo.docx document below acts as the template document.
- The PxPlus promo program uses the Word object to populate the various pieces of data within the square brackets.

promo.docx document:

PxPlus promo program:

> ! promo - Use Word object for mail merge
> !
> OPEN (HFN,IOL=*)"client"
> clients=LFO
> !
> path$="C:\PVX Plus Technologies\PxPlus version_number\word\"
> !
> w=NEW("*obj/word")
> !
> ! populate client name and address data
> search_fields$="ClientName$"+SEP+"Address1$"+SEP+"Address2$"+SEP+"City$"+SEP+"State$"+SEP+"Country$"+SEP+"ZipCode$"+SEP+"ytdSales"+SEP
> SELECT * FROM clients WHERE ytdSales>10000
> promo=w'OpenDocument(path$+"promo.docx")
> !
> ERASE path$+Clientid$+"docx",ERR=*NEXT
> !
> FOR field$ FROM search_fields$
> find$="["+field$+"]"
> IF find$="[ytdSales]" THEN replace$="$"+STP(STR(ytdSales:"###,###.00"),"L"," ") ELSE replace$=VIS(field$)
> w'case_sensitive_search=1
> w'FindReplaceAll(find$,replace$)
> NEXT
> !
> ! populate dates
> w'FindReplaceAll("[TodaysDate]",DTE(0:"%Ml %D,%Y"))
> w'FindReplaceAll("[YearDate]",DTE(0:"%Y"))
> !
> ! highlight '25% off coupon'
> W'FindSetColor("25% off coupon","red")
> !
> w'SaveAsDocument(path$+ClientId$)
> w'PrintDocument(1)
> w'CloseDocument(1)
> !
> NEXT RECORD
> !
> DROP OBJECT w
> CLOSE (clients,ERR=*NEXT)
> !
> END

## See Also

PxPlus Excel Object
Google Workspace Objects