Liren Large Software Subsidy 14/14.iso/s/s005/58.ddi/AMIMACRO.HL$/AMIMACRO.HLP

OS/2 Help File | 1993-11-09 | 960.1 KB | 26,426 lines

ΓòÉΓòÉΓòÉ 1. About ΓòÉΓòÉΓòÉ

This function displays the About Ami Pro dialog box. This function is
equivalent to choosing Help About Ami Pro.


Syntax
About()

Return Value
This function does not return a value.

Example
FUNCTION Example()
About()       'This brings up the About Ami Pro dialog box
END FUNCTION
See also:
    Help
    HowDoIHelp
    MacroHelp
    UsingHelp


ΓòÉΓòÉΓòÉ 2. ActivateApp ΓòÉΓòÉΓòÉ

This function causes the application used in the argument to become the active
application in OS/2. This function is equivalent to choosing the application
from the OS/2 Window List. The application must be started before this command
is used.


Though control passes to the named application, Ami Pro regains control if the
macro continues with additional statements beyond this statement.

Syntax
ActivateApp(App)
App is the name of the application that you want to find. The name you use must
appear as it does in the Window List window or as it does in the application's
title bar.

Return Value
1  (TRUE) if the application was activated.
0  (FALSE) if control could not be passed to the application or if the
application was incorrectly named.

Example
FUNCTION Example()
'Notify the user what we are doing
'Check to see if the app is running
IF AppIsRunning("CMD.EXE")
    'Activate it if it is
    ActivateApp("CMD.EXE")
    'Restore it to its previous size
    AppRestore("CMD.EXE")
ELSE
    'Run it if it is not (it becomes the active app)
    Exec("CMD.EXE", 1)
ENDIF
StatusBarMsg("")  'Clear the status bar
END FUNCTION

See also:

    AppGetAppCount
    AppGetAppNames
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSize
    Exec


ΓòÉΓòÉΓòÉ 3. ADDCascadeMenu ΓòÉΓòÉΓòÉ

This function adds a cascading menu to the end of an existing pull down menu.


Syntax
AddCascadeMenu(BarID, Menu, CascadeMenu)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu this cascade menu should be added to.
This must match exactly the name of the pull down menu you want to add to,
including any ampersand (&) characters. An ampersand is placed before a
character that has an underline.
CascadeMenu is the name of the Cascade menu you want to add. Placing an
ampersand (&) in front of a character makes that character appear underlined
and makes that character a shortcut key.

Return Value
1  (TRUE) if the cascading menu was created.
0  (FALSE) if the cascading menu was not created.

Example
FUNCTION Example()
' Add a new cascade to the page menu
Mac = GetRunningMacroFile$()   ' Name of running macro
Menu = "&Page"
Cascade = "New &Cascade"
DeleteMenuItem(1,Menu,Cascade) ' We don't want multiple cascades
AddCascadeMenu(1, Menu,Cascade)
AddCascadeMenuItem(1, Menu, Cascade, "Item1","{Mac}!Item1()","Help for item1")
AddCascadeMenuItem(1, Menu, Cascade, "My File New",New,"")
AddCascadeMenuItem(1, Menu, Cascade, "My Copy",Copy,"")
End Function

Function Item1()
Message("Nice menu!")
End Function

See also:

    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    DeleteMenuItem
    GrayMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    RenameMenuItem


ΓòÉΓòÉΓòÉ 4. AddCascadeMenuItem ΓòÉΓòÉΓòÉ

This function adds a menu item to an existing cascading menu.


Syntax
AddCascadeMenuItem(BarID, Menu, CascadeMenu, Item, MacroName[!Function[(parm1[,
parm2...])]], Help)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu this cascade menu should be added to.
This must match exactly the name of the pull down menu you want to add to,
including any ampersand (&) characters. An ampersand is placed before a
character that has an underline.
CascadeMenu is the name of the cascade menu you want to add. Placing an
ampersand (&) in front of a character makes that character appear underlined
and makes that character a shortcut key.
Item is the name of the menu item to add. Placing an ampersand (&) in front of
a character makes that character appear underlined and makes that character a
shortcut key. If the menu item has a shortcut key, you must press TAB, type a
^, and then type the appropriate letter as part of the item name.
MacroName is the name of the macro to run if this menu item is selected. This
parameter may contain the macro file name, the function within that file to
call, and any parameters that function may require. At a minimum, this
parameter must contain the macro file name.
Help is the one-line Help text that appears in the title bar of Ami Pro when
this menu item is highlighted. It is not optional for this function.

Return Value
1  (true) if the new menu bar was created.
0  (UserCancel/FALSE) if the new menu bar was not created or if the user
canceled the function.

Example
FUNCTION Example()
' Add a new cascade to the page menu
Mac = GetRunningMacroFile$()   ' Name of running macro
Menu = "&Page"
Cascade = "New &Cascade"
DeleteMenuItem(1,Menu,Cascade) ' We don't want multiple cascades
AddCascadeMenu(1, Menu,Cascade)
AddCascadeMenuItem(1, Menu, Cascade, "Item1","{Mac}!Item1()","Help for item1")
AddCascadeMenuItem(1, Menu, Cascade, "My File New",New,"")
AddCascadeMenuItem(1, Menu, Cascade, "My Copy",Copy,"")
End Function

Function Item1()
Message("Nice menu!")
End Function

See also:

    AddCascadeMenu
    AddMenu
    AddMenuItem
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    DeleteMenuItem
    GrayMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    RenameMenuItem


ΓòÉΓòÉΓòÉ 5. AddFrame ΓòÉΓòÉΓòÉ

This function automatically creates a frame. All dimensions of the frame must
be entered in twips (1 inch = 1440 twips), with the 0,0 location considered to
be the top left corner of the page. This function is equivalent to choosing
Frame Create Frame.


You must be in Layout Mode to call this function.

Syntax
AddFrame(X1, Y1, X2, Y2)
X1 is the horizontal position of the top left corner of the frame.
Y1 is the vertical position of the top left corner of the frame.
X2 is the horizontal position of the bottom right corner of the frame.
Y2 is the vertical position of the bottom right corner of the frame.
The two X coordinates should either be zero or positive numbers. The two Y
coordinates should either be zero or negative numbers.

To display the Add a Frame dialog box and allow the user to select the
coordinates: AddFrameDLG

Return Value
1  (TRUE) if the frame was created.
-2  (GeneralFailure) if the frame was not created.

Example
FUNCTION Example()
Mode = GetMode()     'What mode is the screen in?
IF Mode != TRUE
    LayoutMode()     'If not Layout Mode, make it so.
ENDIF
X1 = 3000         ' horizontal - top left
Y1 = -3000        ' vertical - top right
X2 = 7000         ' horizontal - bottom right
Y2 = -7000        ' vertical - bottom right
AddFrame(X1, Y1, X2, Y2)       ' create frame
END FUNCTION

See also:

    AddFrameDLG
    FrameLayout
    FrameModBorders
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType
    ImportPicture
    IsFrameSelected
    SelectFrameByName
    SetFrameDefaults


ΓòÉΓòÉΓòÉ 6. AddFrameDLG ΓòÉΓòÉΓòÉ

This function displays the Create Frame dialog box. This function is equivalent
to choosing Frame Create Frame.


This function does not automatically create a frame. To create a frame
automatically, refer to the AddFrame function.

You must be in Layout Mode to call this function.

Syntax
AddFrameDLG

Return Value
1  (TRUE) if the frame was created.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
Mode = GetMode()  'What mode is the screen in?
IF Mode != 1
    LayoutMode()  'If not Layout Mode, make it so.
ENDIF
AddFrameDLG          'Display Add Frame dialog box.
END FUNCTION

See also:

    AddFrame
    FrameLayout
    FrameModBorders
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType
    ImportPicture
    IsFrameSelected
    SelectFrameByName
    SetFrameDefaults



ΓòÉΓòÉΓòÉ 7. AddMenu ΓòÉΓòÉΓòÉ

This function creates a new menu on an existing menu bar. The new menu is added
to the right of the last menu on the menu bar.


Syntax
AddMenu(BarID, Menu)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu that should be added. Placing an
ampersand (&) character before a character makes that character appear
underlined and makes that character a shortcut key.

Return Value
1  (TRUE) if the menu was added.
0  (FALSE) if the menu was not added to the menu bar, or if an invalid BarID
was used.

Example
FUNCTION Example()
thisfile = getrunningmacrofile$()
addmenu(1,"&New Menu")      ' create a new menu
addmenuitem(1,"&New Menu","Menu Item &1","{thisfile}!message1()","Display
Message 1")
addmenuitem(1,"&New Menu","Menu Item &2","{thisfile}!message2()","Display
Message 2")
' create a cascade menu
addcascademenu(1,"&New Menu", "Cascade Menu &1")
addcascademenuitem(1,"&New Menu","Cascade Menu &1","Cascade Item &1", "
{thisfile}!message3()","Display Message 3")
addcascademenuitem(1,"&New Menu","Cascade Menu &1","Cascade Item &2", "
{thisfile}!message4()","Display Message 4")
end function

function message1()
message("You selected Menu Item 1.")
end function
function message2()
message("You selected Menu Item 2.")
end function
function message3()
message("You selected Cascade Item 1.")
end function
function message4()
message("You selected Cascade Item 2.")
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenuItem
    ChangeCascadeAction
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    DeleteMenuItem
    GrayMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    RenameMenuItem


ΓòÉΓòÉΓòÉ 8. AddMenuItem ΓòÉΓòÉΓòÉ

This function adds a new menu item to the bottom of an existing pull down menu
or adds an item directly to an existing menu bar.


Syntax
AddMenuItem(BarID, Menu, Item, MacroName[!Function[(parm1[, parm2...])]][,
Help])
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu to which this item should be added. This
name must match the name of the pull down menu, including any ampersand (&)
characters. An ampersand is placed before a character that has an underline.
Item is the name of the menu item to add. Placing an ampersand (&) in front of
a character makes that character appear underlined and makes that character a
shortcut key. If the menu item has a shortcut key, you must press TAB, type a
^, and then type the appropriate letter as part of the item name.
MacroName is the name of the macro to run if this menu item is selected. This
parameter may contain the macro file name, the function within that file to
call, and any parameters that function may require. At a minimum, this
parameter must contain the macro file name. If you want to run an Ami Pro
function, use its name without quotes or parentheses.
Help is the optional one-line Help text that appears in the title bar of Ami
Pro when this menu item is highlighted.
If you want the item on the menu bar: AddMenuItem

Return Value
This function returns:
1  (TRUE) if the new menu item was added.
0  (FALSE) if the new menu item was not added, or if an invalid BarID or
MenuName was used.

Example
FUNCTION Example()
thisfile = getrunningmacrofile$()
addmenu(1,"&New Menu")      ' create a new menu
addmenuitem(1,"&New Menu","Menu Item &1","{thisfile}!message1()","Display
Message 1")
addmenuitem(1,"&New Menu","Menu Item &2","{thisfile}!message2()","Display
Message 2")
' create a cascade menu
addcascademenu(1,"&New Menu", "Cascade Menu &1")
addcascademenuitem(1,"&New Menu","Cascade Menu &1","Cascade Item &1", "
{thisfile}!message3()","Display Message 3")
addcascademenuitem(1,"&New Menu","Cascade Menu &1","Cascade Item &2", "
{thisfile}!message4()","Display Message 4")
end function

function message1()
message("You selected Menu Item 1.")
end function
function message2()
message("You selected Menu Item 2.")
end function
function message3()
message("You selected Cascade Item 1.")
end function
function message4()
message("You selected Cascade Item 2.")
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    ChangeCascadeAction
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    DeleteMenuItem
    GetMacPath
    GrayMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    RenameMenuItem


ΓòÉΓòÉΓòÉ 9. AllocGlobalVar ΓòÉΓòÉΓòÉ

This function allocates memory to hold a global variable (single element or
array). Global variables retain their values until the user frees them or exits
Ami Pro, as opposed to regular variables, which are lost once the macro is
finished.


Syntax
AllocGlobalVar(Name, Count)
Name is a unique number or string naming the variable being allocated.
Count is the number of entries to allocate. A count of one allocates a single
element global variable. A count of more than one allocates an array with count
elements.

Return Value
The Name if the variable allocates memory.
0  (FALSE) if there is no free memory to allocate.

Example
FUNCTION Example()
varname = Query$("What do you wish to name the global variable?")
AllocGlobalVar("{varname}", 1)
Message("The variable {varname} has been allocated room in memory to hold one
entry.")
varvalue = Query$("Enter some data to put in this global variable called
{varname}.")
SetGlobalVar("{varname}", "{varvalue}")
Message("Ok, we will now go and get the value of {varname} and display it.")
Message(GetGlobalVar$("{varname}"))
END FUNCTION

See also:

    FreeGlobalVar
    GetGlobalArray$
    GetGlobalVar$
    GetGlobalVarCount
    GetGlobalVarNames
    Global Variables
    SetGlobalArray
    SetGlobalVar



ΓòÉΓòÉΓòÉ 10. AmiProIndirect ΓòÉΓòÉΓòÉ

This function is used to call any Ami Pro function where the number of
parameters cannot be determined ahead of time.


Syntax
AmiProIndirect(FunctionName, &Parameters, Count)
FunctionName is the function you want to call.
Parameters are the arrays that contain the parameters.
Count is the number of parameters in the array.

Return Value
1  (TRUE) if the changes were made.
0  (FALSE) if the changes could not be made.

Example
FUNCTION Example()
' how many parameters?
ParamCount = GetLayoutParmCnt(ModLayoutRightPage)
' dimension an array for the parameters
DIM LayoutValues(ParamCount)
' get the values
GetLayoutParameters(ModLayoutRightPage, &LayoutValues)
' increase the top margin by 1 inch
LayoutValues(2) = LayoutValues(1) + 1440
' prepare Ami Pro for a layout change
ModLayoutInit(512) ' apply layout
AmiProIndirect(ModLayoutRightPage, &LayoutValues, ParamCount)
ModLayoutFinish() ' let Ami Pro accept the changes
END FUNCTION

See also:

    GetLayoutParameters
    ModLayoutFinish
    ModLayoutInit
    ModLayoutRightPage



ΓòÉΓòÉΓòÉ 11. AnswerMsgBox ΓòÉΓòÉΓòÉ

This function is used to 'reply' to an Ami Pro function that asks the user for
a response. Many functions require the user to provide some response before the
function can be completed. The Messages function allows the macro programmer to
decide if the user has to respond to messages or if the default action is
taken. The AnswerMsgBox function works in a similar manner; however, a response
determined by the programmer is taken, rather than the default.


The AnswerMsgBox function should be used immediately before the function which
displays the message. Unlike the Messages function, the AnswerMsgBox function
provides a response only to the next Ami Pro function called, rather than all
succeeding messages.

In general, within a given macro, you should not mix the Messages and
AnswerMsgBox functions.

Syntax
AnswerMsgBox(Response)
Response is the desired response to a message box displayed by a function. It
must be set to one of the following options:
    OK (1) - Equivalent to choosing OK
    Cancel (2) - Equivalent to choosing Cancel
    Abort (3) - Equivalent to choosing Abort
    Retry (4) - Equivalent to choosing Retry
    Yes (6) - Equivalent to choosing Yes
    No (7) - Equivalent to choosing No

Return Value
This function does not return a value.

Example
FUNCTION Example()
New("_default.sty", 0, 0)
Type("Lotus Ami Pro for OS/2")
Message("New file created. Press OK to close without saving.")
AnswerMsgBox(7)
FileClose()
END FUNCTION

See also:

    HourGlass
    IgnoreKeyboard
    Messages
    SingleStep
    UserControl



ΓòÉΓòÉΓòÉ 12. AppClose ΓòÉΓòÉΓòÉ

This function closes any OS/2 application.


Syntax
AppClose(App)
App is the name of the application which should be closed. The name you use
must appear as it does in the OS/2 Window List or as it does in the
application's title bar.

Return Value
1  (TRUE) if the changes were made.
0  (FALSE) if the changes could not be made.

Example
FUNCTION Example()
exec("E.EXE", "", 1)
message("About to close E.")
AppClose("E.EXE")
END FUNCTION

See also:

    ActivateApp
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize




ΓòÉΓòÉΓòÉ 13. AppGetAppCount ΓòÉΓòÉΓòÉ

This function allows you to get the number of currently running OS/2
applications. It is usually used to dimension an array before the
AppGetAppNames function is called.


Syntax
AppGetAppCount()

Return Value
The number of running OS/2 applications.

Example
FUNCTION Example()
numapps = AppGetAppCount()     'return the number of apps
Message("Currently, there are {numapps} applications running, whether hidden or
visible.")
DIM names(numapps)          'dimension a name array
AppGetAppNames(&names)      'get the name for the apps
FOR I = 1 to numapps    'show the name for each app
    app = names(I)
    Message(app)
NEXT
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize


ΓòÉΓòÉΓòÉ 14. AppGetAppNames ΓòÉΓòÉΓòÉ

This function retrieves the names of all of the currently running OS/2
applications and places them in an array. The array may be dimensioned using
the AppGetAppCount function.


Syntax
AppGetAppNames(&Array)
Array is the name of an array, dimensioned from the return value of the
AppGetAppCount function. Note the use of indirection (&).

Return Value
The number of applications.

Example
FUNCTION Example()
numapps = AppGetAppCount()     'return the number of apps
Message("Currently, there are {numapps} applications running, whether hidden or
visible.")
DIM names(numapps)          'dimension a name array
AppGetAppNames(&names)      'get the name for the apps
FOR I = 1 to numapps    'show the name for each app
    app = names(I)
    Message(app)
NEXT
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize


ΓòÉΓòÉΓòÉ 15. AppGetWindowPos ΓòÉΓòÉΓòÉ

This function returns the location and size information about any OS/2
application. Note the use of indirection (&). The X, Y, Width, and Height
parameters are all passed by addressing. The return values are in percentages
of the screen size.


Syntax
AppGetWindowPos(App, &X, &Y, &Width, &Height)
App is the name of the application that you want to find. The name you use must
appear as it does in the OS/2 Window List or as it does in the application's
title bar.
X is the horizontal starting point of App.
Y is the vertical starting point of App.
Width is the width of App.
Height is the height of App.

Return Value
1  (TRUE) if the application was valid.
0  (FALSE) if the application was not valid.

Example
FUNCTION Example()
defstr x,y,x2,y2;
exec("E.EXE", "", 1)
AppgetWindowPos("E.EXE", &x, &y, &x2, &y2)
Message("About to move window")
AppMove("E.EXE", 10,20)
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize



ΓòÉΓòÉΓòÉ 16. AppHide ΓòÉΓòÉΓòÉ

This function hides any OS/2 application. When an application is hidden it
cannot receive keyboard or mouse input; however, it responds to Dynamic Data
Exchange (DDE) commands.


Syntax
AppHide(App)
App is the name of the application that should be hidden. The name you use must
appear as it does in the OS/2 Window List or as it does in the application's
title bar.

Return Value
1  (TRUE) if the application was hidden.
0  (FALSE) if the application could not be hidden.

Example
FUNCTION Example()
if appisrunning("E.EXE")
    ActivateApp("E.EXE")
else
    Exec("E.EXE", "", 1)
endif
message("About to hide E.")
AppHide("E.EXE")
message("About to restore E.")
AppRestore("E.EXE")
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize


ΓòÉΓòÉΓòÉ 17. AppIsRunning ΓòÉΓòÉΓòÉ

This function allows you to see if any OS/2 application is currently running.


Syntax
AppIsRunning(App)
App is the name of the application to be evaluated. The name you use must
appear as it does in the OS/2 Window List or as it does in the application's
title bar.

Return Value
1  (TRUE) if the application is running.
0  (FALSE) if the application is not running.

Example
FUNCTION Example()
if appisrunning("E.EXE")
    ActivateApp("E.EXE")
else
    Exec("E.EXE", "", 1)
endif
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize


ΓòÉΓòÉΓòÉ 18. ApplyFormat ΓòÉΓòÉΓòÉ

This function applies text formatting to selected text. The text formatting
must be loaded using the FastFormat function.


A macro must be edited to insert this non-recordable function.

Syntax
ApplyFormat()

Return Value
This function returns 1.

Example
FUNCTION Example()
UserControl("Shade the area that contains the formatting you want:")
FastFormat()   ' Turn on Fast Formatting
FastFormat()   ' Turn off Fast Formatting
UserControl("Shade the area you want to apply formatting to:")
ApplyFormat()
END FUNCTION

See also:

    FastFormat


ΓòÉΓòÉΓòÉ 19. AppMaximize ΓòÉΓòÉΓòÉ

This function maximizes any OS/2 application.


Syntax
AppMaximize(App)
App is the name of the application that is to be maximized. The name you use
must appear as it does in the OS/2 Window List or as it does in the
application's title bar.

Return Value
1  (TRUE) if the application was maximized.
0  (FALSE) if the application could not be maximized.

Example
FUNCTION Example()
Exec("pmamifm.exe", "", 1)
AppMaximize("File Manager")
Message("File Manager is maximized.")
AppRestore("File Manager")
Message("File Manager is windowed.")
AppMinimize("File Manager")
Message("File Manager is an icon.")
ActivateApp("File Manager")
Message("Click OK to close File Manager.")
AppClose("File Manager")
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize


ΓòÉΓòÉΓòÉ 20. AppMinimize ΓòÉΓòÉΓòÉ

This function minimizes any OS/2 application.


Syntax
AppMinimize(App)
App is the name of the application that is to be minimized. The name you use
must appear as it does in the OS/2 Window List or as it does in the
application's title bar.

Return Value
1  (TRUE) if the application was minimized.
0  (FALSE) if the application could not be minimized.

Example
FUNCTION Example()
Exec("PMAMIFM.EXE", "", 1)
AppMaximize("File Manager")
Message("File Manager is maximized.")
AppRestore("File Manager")
Message("File Manager is windowed.")
AppMinimize("File Manager")
Message("File Manager is an icon.")
ActivateApp("File Manager")
Message("Click OK to close File Manager.")
AppClose("File Manager")
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMove
    AppRestore
    AppSendMessage
    AppSize


ΓòÉΓòÉΓòÉ 21. AppMove ΓòÉΓòÉΓòÉ

This function moves a OS/2 application. It does not size the window, but moves
it to a new location on the screen.


Syntax
AppMove(App, X, Y)
App is the name of the application that is to be moved. The name you use must
appear as it does in the OS/2 Window List or as it does in the application's
title bar. To identify Ami Pro as the application to move, use the null string
("").
X is the horizontal location on the screen, in percent.
Y is the vertical location on the screen, in percent.
(0,0) is the upper left position on the screen.

Return Value
1  (TRUE) if the application was moved.
0  (FALSE) if the application could not be moved.

Example
FUNCTION Example()
defstr x,y,x2,y2;
exec("E.EXE", "", 1)
AppgetWindowPos("E.EXE", &x, &y, &x2, &y2)
Message("About to move window")
AppMove("E.EXE", 10,20)
END FUNCTION


See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppRestore
    AppSendMessage
    AppSize



ΓòÉΓòÉΓòÉ 22. AppRestore ΓòÉΓòÉΓòÉ

This function restores any OS/2 application to its former non-maximized or
non-minimized size.


Syntax
AppRestore(App)
App is the name of the application that is to be restored. The name you use
must appear as it does in the OS/2 Window List or as it does in the
application's title bar.

Return Value
1  (TRUE) if the application was restored.
0  (FALSE) if the application could not be restored.

Example
FUNCTION Example()
if appisrunning("E.EXE")
    ActivateApp("E.EXE")
else
    Exec("E.EXE", "", 1)
endif
message("About to hide E.")
AppHide("E.EXE")
message("About to restore E.")
AppRestore("E.EXE")
END FUNCTION


See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppSendMessage
    AppSize



ΓòÉΓòÉΓòÉ 23. AppSendMessage ΓòÉΓòÉΓòÉ

This function allows you to send any OS/2 message to any OS/2 application. You
should be familiar with the Message, Wparam, and Lparam parameters. This
function first locates the application's handle and then calls the SendMessage
function from OS/2 with the specified parameters.


Syntax
AppSendMessage(App, Message, Wparam, Lparam)
App is the name of the application to send the message to. It can also be a
window handle.
Message is the OS/2 message to send to the application.
Wparam is the wparam parameter for the OS/2 message.
Lparam is the lparam parameter for the OS/2 message.

Return Value
The return value from the OS/2 function SendMessage.

Example
DEFINE Em_SetPassWord   1052
DEFINE Asterisk      42

FUNCTION Example()
' get the name of this macro file
Mac = GetRunningMacrofile$()
' this is called before the box is displayed
SetDlgCallBack(0,"{Mac}!InitDlg")
Box = DialogBox(".","Pass")
pword = GetDialogField$(8000)
Message("Password was {pword}")
END FUNCTION

FUNCTION InitDlg(Hdlg, id, value)
' Get the handle to the edit box 8000
hEditBox = GetDlgItem(Hdlg, 8000)
' Password protect edit box
AppSendMessage(hEditbox,Em_SetPassWord,Asterisk,0)
END FUNCTION

DIALOG Pass
-2134376448 2 80 51 160 52 "" "" "Password Example"
FONT 8 "Helv"
6 22 100 12 8000 1350631552 "edit" "" 0
116 4 40 14 1 1342242817 "button" "OK" 0
END DIALOG

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSize
    SetDlgCallback


ΓòÉΓòÉΓòÉ 24. AppSize ΓòÉΓòÉΓòÉ

This function changes the size of any OS/2 application.


Syntax
AppSize(App, Width, Height)
App is the name of the application that is to be sized. The name you use must
appear as it does in the OS/2 Window List or as it does in the application's
title bar. Using null ( "" ) will cause AppSize to affect the current Ami Pro
window.
Width is the new width, as a percentage of screen size, of the App.
Height is the new height, as a percentage of screen size, of the App.

Return Value
1  (TRUE) if the application was successfully sized.
0  (FALSE) if the application could not be sized.

Example
FUNCTION Example()
defstr x,y,x2,y2;
exec("E.EXE", "", 1)
AppGetWindowPos("E.EXE", &x, &y, &x2, &y2)
Message("About to size window")
AppSize("E.EXE", 10,20)
END FUNCTION

See also:

    ActivateApp
    AppClose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage



ΓòÉΓòÉΓòÉ 25. ArrayDelete ΓòÉΓòÉΓòÉ

This function deletes the specified record from an existing array. This
function does not re-dimension the array.


Syntax
ArrayDelete(&Array, Index)
Array is the name of the array from which to delete a record. Note the use of
indirection (&).
Index is the location in the array to delete. This parameter must be a valid
array index.

Return Value
1  (TRUE) if the record could be deleted.
0  (FALSE) if the record could not be deleted.

Example
FUNCTION Example()
as = Query$("How many records do you want this array to hold?")
DIM Names(as)     ' dimension the name array
FOR I = 1 to as
    ThisName = Query$("What is this person's Name?")
    IF ThisName != ""'if not blank, insert the name
       ArrayInsert(&Names, 1, ThisName)
    ENDIF
NEXT
Size = ArraySize(&Names)    'return the number of names
Message("Number of records is {Size}.")
ArraySort(&Names)       'sort the names
Again:
' Find the location of the name
Ndex = ArraySearch(&Names, Query$("What name to find?"))
IF Ndex != 0
    IF Decide("Do you want to delete record {Ndex}?")
       ' delete the record at that index
       ArrayDelete(&Names, Ndex)
       ' shrink the size of the array
       Size = Size - 1
    ENDIF
ELSE
    Message("Could not find record.")
    GoTo again
ENDIF
FOR I = 1 to Size
    ThisName = Names(I)
    Message("Record Number {I} of {Size} is {ThisName}.")
NEXT
END FUNCTION

See also:

    ArrayInsertByKey
    ArrayInsert
    ArraySearch
    ArraySize
    ArraySort
    Declaring Formal Variables Using the DIM Statement


ΓòÉΓòÉΓòÉ 26. ArrayInsert ΓòÉΓòÉΓòÉ

This function inserts the specified record into the array at the specified
index. It "moves" existing records to make room for the new record. If the
array is full, the function expands the array.


Syntax
ArrayInsert(&Array, Index, Record)
Array is the name of the array in which to insert the specified record. Note
the use of indirection (&).
Index is the position in the array to insert the specified record. Index must
be a valid array index or one greater than the full array. If the array index
is greater than the current size of the array by one, the record appends to the
end of the array.
Record is the data to insert into the array.
The name of the array uses indirection (&).

Return Value
1  (TRUE) if the record was inserted.
0  (FALSE) if the record could not be inserted.

Example
FUNCTION Example()
as = Query$("How many records do you want this array to hold?")
DIM Names(as)     ' dimension the name array
FOR I = 1 to as
    ThisName = Query$("What is this person's Name?")
    IF ThisName != ""'if not blank, insert the name
       ArrayInsert(&Names, 1, ThisName)
    ENDIF
NEXT
Size = ArraySize(&Names)    'return the number of names
Message("Number of records is {Size}.")
ArraySort(&Names)       'sort the names
Again:
' Find the location of the name
Ndex = ArraySearch(&Names, Query$("What name to find?"))
IF Ndex != 0
    IF Decide("Do you want to delete record {Ndex}?")
       ' delete the record at that index
       ArrayDelete(&Names, Ndex)
       ' shrink the size of the array
       Size = Size - 1
    ENDIF
ELSE
    Message("Could not find record.")
    GoTo again
ENDIF
FOR I = 1 to Size
    ThisName = Names(I)
    Message("Record Number {I} of {Size} is {ThisName}.")
NEXT
END FUNCTION

See also:

    ArrayDelete
    ArrayInsertByKey
    ArraySearch
    ArraySize
    ArraySort
    Declaring Formal Variables Using the DIM Statement




ΓòÉΓòÉΓòÉ 27. ArrayInsertByKey ΓòÉΓòÉΓòÉ

This function inserts the record based on the assumption that the array is
sorted. The array can be a single element array or field delimited records. If
the array is full, the function expands the array.


Syntax
ArrayInsertByKey(&Array, Record, DuplicatesOk[, FieldNumber, Delimiter])
Array is the name of the array in which to insert the specified record. Note
the use of indirection (&).
Record is the data to insert into the array.
DuplicatesOk determines if this record should be inserted if its key is already
in the array. If the DuplicatesOk parameter is TRUE and this record has a
duplicate key, the record is inserted after all other records with the same
key.
FieldNumber is the optional field number when using field delimited records.
This defines the Key field.
Delimiter is the optional delimiter in field delimited records.

Return Value
A positive number which is the index of the inserted record.
0  (FALSE) if the record was not inserted.

Example
FUNCTION Example()
as = Query$("How many records do you want this array to hold?")
DIM Names(as)     'dimension the name array
FOR I = 1 to as
    ThisName = Query$("What is this one's name?")
    ArrayInsertByKey(&Names, ThisName, TRUE)
NEXT
Size = ArraySize(&Names)
FOR I = 1 to Size
    ThisName = Names(I)
    Message("Record #{I} of {Size} is {ThisName}.")
NEXT
END FUNCTION

See also:

    ArrayDelete
    ArrayInsert
    ArraySearch
    ArraySize
    ArraySort
    Declaring Formal Variables Using the DIM Statement




ΓòÉΓòÉΓòÉ 28. ArraySearch ΓòÉΓòÉΓòÉ

This function searches the specified array looking for a key. If a FieldNumber
and a  delimiter are specified, the function assumes the records are field
delimited and matches only on the specified field. If duplicate matches occur,
this function finds the first matching record. If an index is specified, the
function begins searching at that position and returns the next matching index
of the record.


Syntax
ArraySearch(&Array, Key[, FieldNumber, Delimiter][, Index])
Array is the name of the array to search. Note the use of indirection (&).
Key is the data to search for.
FieldNumber is the optional field number when using field delimited records.
This defines the Key field.
Delimiter is the optional delimiter in field delimited records.
Index is the position in the array to begin the search.

Return Value
A positive number which is the index of the matching record.
0  (FALSE) if the record was not matched.

Example
FUNCTION Example()
as = Query$("How many records do you want this array to hold?")
DIM Names(as)     ' dimension the name array
FOR I = 1 to as
    ThisName = Query$("What is this person's Name?")
    IF ThisName != ""'if not blank, insert the name
       ArrayInsert(&Names, 1, ThisName)
    ENDIF
NEXT
Size = ArraySize(&Names)    'return the number of names
Message("Number of records is {Size}.")
ArraySort(&Names)       'sort the names
Again:
' Find the location of the name
Ndex = ArraySearch(&Names, Query$("What name to find?"))
IF Ndex != 0
    IF Decide("Do you want to delete record {Ndex}?")
       ' delete the record at that index
       ArrayDelete(&Names, Ndex)
       ' shrink the size of the array
       Size = Size - 1
    ENDIF
ELSE
    Message("Could not find record.")
    GoTo again
ENDIF
FOR I = 1 to Size
    ThisName = Names(I)
    Message("Record Number {I} of {Size} is {ThisName}.")
NEXT
END FUNCTION

See also:

    ArrayDelete
    ArrayInsertByKey
    ArrayInsert
    ArraySize
    ArraySort
    Declaring Formal Variables Using the DIM Statement



ΓòÉΓòÉΓòÉ 29. ArraySize ΓòÉΓòÉΓòÉ

This function returns the number of elements in an existing array.


Syntax
ArraySize(&Array)
Array is the name of the array to be examined. Note the use of indirection (&).

Return Value
The number of dimensioned elements in the array.

Example
FUNCTION Example()
as = Query$("How many records do you want this array to hold?")
DIM Names(as)     ' dimension the name array
FOR I = 1 to as
    ThisName = Query$("What is this person's Name?")
    IF ThisName != ""'if not blank, insert the name
       ArrayInsert(&Names, 1, ThisName)
    ENDIF
NEXT
Size = ArraySize(&Names)    'return the number of names
Message("Number of records is {Size}.")
ArraySort(&Names)       'sort the names
Again:
' Find the location of the name
Ndex = ArraySearch(&Names, Query$("What name to find?"))
IF Ndex != 0
    IF Decide("Do you want to delete record {Ndex}?")
       ' delete the record at that index
       ArrayDelete(&Names, Ndex)
       ' shrink the size of the array
       Size = Size - 1
    ENDIF
ELSE
    Message("Could not find record.")
    GoTo again
ENDIF
FOR I = 1 to Size
    ThisName = Names(I)
    Message("Record Number {I} of {Size} is {ThisName}.")
NEXT
END FUNCTION

See also:

    ArrayDelete
    ArrayInsertByKey
    ArrayInsert
    ArraySearch
    ArraySort
    Declaring Formal Variables Using the DIM Statement




ΓòÉΓòÉΓòÉ 30. ArraySort ΓòÉΓòÉΓòÉ

This function sorts an existing array in ascending order. If a FieldNumber and
D elimiter are specified, the function assumes the records are field delimited
and the sort is performed on the specified field. If duplicate keys exist,
their order is undefined.


Numbers sort before alphabetical characters.

Syntax
ArraySort(&Array[, FieldNumber, Delimiter])
Array is the name of the array to be sorted. Note the use of indirection (&).
FieldNumber is the optional field number when using field delimited records.
This defines the Key field.
Delimiter is the optional delimiter in field delimited records.

Return Value
1  (TRUE) if the array was sorted.
0  (FALSE) if the array could not be sorted.

Example
FUNCTION Example()
as = Query$("How many records do you want this array to hold?")
DIM Names(as)     ' dimension the name array
FOR I = 1 to as
    ThisName = Query$("What is this person's Name?")
    IF ThisName != ""'if not blank, insert the name
       ArrayInsert(&Names, 1, ThisName)
    ENDIF
NEXT
Size = ArraySize(&Names)    'return the number of names
Message("Number of records is {Size}.")
ArraySort(&Names)       'sort the names
Again:
' Find the location of the name
Ndex = ArraySearch(&Names, Query$("What name to find?"))
IF Ndex != 0
    IF Decide("Do you want to delete record {Ndex}?")
       ' delete the record at that index
       ArrayDelete(&Names, Ndex)
       ' shrink the size of the array
       Size = Size - 1
    ENDIF
ELSE
    Message("Could not find record.")
    GoTo again
ENDIF
FOR I = 1 to Size
    ThisName = Names(I)
    Message("Record Number {I} of {Size} is {ThisName}.")
NEXT
END FUNCTION

See also:

    ArrayDelete
    ArrayInsertByKey
    ArrayInsert
    ArraySearch
    ArraySize
    Declaring Formal Variables Using the DIM Statement




ΓòÉΓòÉΓòÉ 31. ASC ΓòÉΓòÉΓòÉ

This function determines the numeric code page value of the first letter in the
text. If the text contains more than one letter, the remaining letters are
ignored.


Syntax
ASC(Text)
Text is a string of one or more letters.

Return Value
A number that is the code page value of the first letter in the text.

Example
FUNCTION Example()
String = Query$("What character to return the Value of?")
Number = ASC(String)
Message("The code page equivalent of {String} is {Number}.")
END FUNCTION

See also:

    CHR$
    Instr
    LCASE$
    Left$
    LEN
    MID$
    Right$
    strcat$
    strchr
    strfield$
    UCASE$




ΓòÉΓòÉΓòÉ 32. ASCIIOptions ΓòÉΓòÉΓòÉ

This function sets the ASCII options for any opened file that uses the ASCII
filter. This function is equivalent to choosing File Open, specifying ASCII as
the file type, and choosing ASCII Options.


Syntax
ASCIIOptions(Options)
Options is the options available to open an ASCII file. It is one or more of
the following values:
    CRLF (2) - Expect carriage return/line feed characters at end of lines; if
    not set, expect CR/LFs at end of paragraphs
    PCASCII (8) - 8 bit PC ASCII file
    ANSI (16) - 8 bit ANSI file
    KeepNames (32) - Keep style names

Return Value
This function returns 1.

Example
Function Example()
AsciiOptions(PCASCII)
FileOpen("c:\autoexec.bat", 16, "ASCII")
end function

See also:

    FileOpen
    ImportExport
    SaveAs



ΓòÉΓòÉΓòÉ 33. Assign ΓòÉΓòÉΓòÉ

This function assigns the result of an expression to a variable and returns the
same result. The expression can be anything that you can pass to another
function. This function is useful when using IF/THEN and WHILE/WEND statements.


Syntax
Assign(&Var, Express)
Var is the name of the variable to assign the return value from Express to.
Note the use of indirection (&).
Express is the expression to evaluate.

Return Value
The return value of Express.

Example
FUNCTION Example()
DEFSTR id, Line;
'if the open file can be assigned to id
IF 0 != Assign(&id, fopen("c:\autoexec.bat", "r"))
    New("_DEFAULT.STY", 0, 0)  'new file
    WHILE -1 != Assign(&Line, fgets$(id))
       TYPE("{Line}[Enter]") 'type the autoexec lines
    WEND
    fclose(id)
ELSE
    Message("Could not open C:\AUTOEXEC.BAT")
ENDIF
END FUNCTION

See also:

    Declaring Formal Variables Using the DEFSTR Statement
    fclose
    fgets$
    fopen
    Using the IF/THEN Statements
    Using the WHILE Statement




ΓòÉΓòÉΓòÉ 34. AssignMacroToFile ΓòÉΓòÉΓòÉ

This function assigns an open and close macro to the current file. This
function is equivalent to choosing Tools Macro Edit and choosing Assign.


Syntax
AssignMacroToFile(OpenMacro, CloseMacro, Flag)
OpenMacro is the macro name that is specified to run when the current file
opens. Use the null string ("") to specify no opening macro.
CloseMacro is the macro name that is specified to run when the current file
closes. Use the null string ("") to specify no closing macro.
Flag indicates whether to run the specified open or close macro. Add the values
together to run both open and close macros.
    2 - Run the opening macro
    4 - Run the closing macro

Return Value
This function returns 0.

Example
FUNCTION Example()
' assign the openit macro to run when you open the doc
' assign the closeit macro to run when you close the doc
AssignMacroToFile("Openit.smm", "Closeit.smm", 6)
END FUNCTION

See also:

    MacroEdit
    MacroOptions
    MacroPlay


ΓòÉΓòÉΓòÉ 35. AtEOF ΓòÉΓòÉΓòÉ

This function determines if the insertion point is at the end of the document.


Syntax
AtEOF()

Return Value
1 (TRUE) if the insertion point is at the end of the document.
0 (FALSE) if the insertion point is not at the end of the document.

Example
FUNCTION Example()
New("_default.sty", 0, 0)
Type("This is the time for all good men to come to the aid of their country.")
Sendkeys("[ctrlhome]")      'go to the beginning of the doc
WHILE not AtEOF()
    Sendkeys("[right]") 'move the cursor right one character
WEND
Message("The insertion point is now at the end of this file.")
END FUNCTION

See also:

    CurChar$
    CurWord$
    EndOfFile
    GetPageNo
    TopOfFile
    Type



ΓòÉΓòÉΓòÉ 36. Beep ΓòÉΓòÉΓòÉ

This function tells OS/2 to sound (beep) the current audio device if the sound
is turned on in the System Setup.


Syntax
Beep()

Return Value
This function does not return a value.

Example
FUNCTION Example()
numbeeps = Query$("How many beeps do you want to hear?", 50)
FOR I = 1 to numbeeps
    Beep()
NEXT
END FUNCTION

See also:

    HourGlass
    Message
    StatusBarMsg




ΓòÉΓòÉΓòÉ 37. BinToBrackets ΓòÉΓòÉΓòÉ

This function takes binary information and converts it to the Ami Pro brackets
convention. This function is useful after using the fread function to see
exactly what was read.


Syntax
BinToBrackets(Data)
Data is the binary information you want to convert to brackets.

Return Value
The bracket convention to which the binary information equates.

Example
FUNCTION Example()
DEFSTR string;
id = fopen("test.txt", "w")    'open test.txt for write
IF id != 0    ' get the name and address
    Name = Query$("What is your name?")
    fwrite(id, Name)
    ' convert to binary
    fwrite(id, BracketsToBin([Enter]))
    fputs(id, Query$("What is your address?"))
    fclose(id)
ENDIF
id2 = fopen("test.txt", "r")       'open test.txt for read
IF id2 != 0
    NameLength = len(Name)     'get the length of the name
    fseek(id2, 0, 0)
    Name = fread(id2, NameLength)
    ' convert to brackets from binary
    EnterKey = BinToBrackets(fread(id2, 2))
    AddressBegins = ftell(id2)
    Address = fgets$(id2)
    Message("Your name is {Name}.")
    Message("Your address is {Address}.")
    Message("EnterKey code is = {EnterKey}")
    Message("Your address begins at the number {AddressBegins} byte in
 TEST.TXT.")
    fclose(id2)
ENDIF
END FUNCTION

See also:

    ASC
    BracketsToBin
    CHR$
    fclose
    fgets$
    fopen
    fputs
    fread
    fwrite



ΓòÉΓòÉΓòÉ 38. Bold ΓòÉΓòÉΓòÉ

This function sets the bold attribute for selected text or all following text
if no text is selected. It acts as a toggle, turning off the attribute if it is
currently on and turning on the attribute if it is currently off. This function
is equivalent to choosing Text Bold. This  function toggles the bold attribute
on or off, depending on its current state.


Syntax
Bold()

Return Value
0   if the bold attribute is toggled on and there are no attributes assigned to
the text.
4   if the bold attribute is toggled off.
8   if the bold attribute is toggled on and the italic attribute is assigned.
16  if the bold attribute is toggled on and the underline attribute is already
assigned.
32  if the bold attribute is toggled on and the word underline attribute is
already assigned.
-2  (GeneralFailure) if the text was not changed.
The return values may be added together to identify the attributes that were
previously assigned.

Example
FUNCTION Example()
text = Query$("Enter some text:")
New("_default.sty", 0, 0)      'open a new file
TYPE("{text}")
TYPE("[enter]")
TYPE("[ctrlhome][ctrlshiftend]")
Copy() 'copy text to clipboard
FOR I = 1 to 10
    Paste()   'paste text 10 times
NEXT
Message("The text will be shaded, bolded, italicized, underlined, and
centered.")
TYPE("[ctrlhome][ctrlshiftend]")
Bold()
Italic()
Underline()
Center()
TYPE("[ctrlhome]")
END FUNCTION

See also:

    Italic
    NormalText
    Underline
    WordUnderline




ΓòÉΓòÉΓòÉ 39. BracketsToBin ΓòÉΓòÉΓòÉ

This function converts Ami Pro bracketed values to their binary equivalents. It
is useful when you are using the fwrite function.


Syntax
BracketsToBin(Data)
Data is the bracketed information to convert to binary.

Return Value
The binary equivalent to the bracketed information.

Example
FUNCTION Example()
DEFSTR string;
id = fopen("test.txt", "w")    'open test.txt for write
IF id != 0    ' get the name and address
    Name = Query$("What is your name?")
    fwrite(id, Name)
    ' convert to binary
    fwrite(id, BracketsToBin([Enter]))
    fputs(id, Query$("What is your address?"))
    fclose(id)
ENDIF
id2 = fopen("test.txt", "r")       'open test.txt for read
IF id2 != 0
    NameLength = len(Name)     'get the length of the name
    fseek(id2, 0, 0)
    Name = fread(id2, NameLength)
    ' convert to brackets from binary
    EnterKey = BinToBrackets(fread(id2, 2))
    AddressBegins = ftell(id2)
    Address = fgets$(id2)
    Message("Your name is {Name}.")
    Message("Your address is {Address}.")
    Message("EnterKey code is = {EnterKey}")
    Message("Your address begins at the number {AddressBegins} byte in
 TEST.TXT.")
    fclose(id2)
ENDIF
END FUNCTION

See also:

    ASC
    BinToBrackets
    CHR$
    fclose
    fgets$
    fopen
    fputs
    fread
    fwrite




ΓòÉΓòÉΓòÉ 40. BringFrameToFront ΓòÉΓòÉΓòÉ

This function brings the selected frame to the front of a stack of frames for
editing. This function is equivalent to choosing Frame Bring to Front.


Syntax
BringFrameToFront()

Return Value
1 (TRUE) if the frame was brought to the front.
0 (NoAction) if no action was taken because the frame was already brought to
the front.

Example
FUNCTION Example()
'get the cursor position
x = strfield$(CursorPosition$(), 1, ",")
y = strfield$(CursorPosition$(), 2, ",")
' add the frames and bookmark them
AddFrame(x, y, (x + 1440), (y - 1440))
MarkBookMark("Frame1", AddBookMark)
AddFrame((x + 360), (y - 360), (x + 1800), (y - 1800))
MarkBookMark("Frame2", AddBookMark)
SendFrameToBack()    ' send frame to back
MarkBookMark("Frame1", FindBookMark)
Message("The First frame is in front.")
MarkBookMark("Frame2", FindBookMark)
BringFrameToFront()  'bring frame to front
Message("The Second frame is in front.")
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    GoToCmd
    SelectFrameByName
    SendFrameToBack


ΓòÉΓòÉΓòÉ 41. CascadeWindow ΓòÉΓòÉΓòÉ

This function cascades and overlaps multiple open windows with the currently
active window on top. This function is equivalent to choosing Window Cascade.


Syntax
CascadeWindow()

Return Value
This function does not return a value.

Example
FUNCTION Example()
Text = UCASE$(Left$(Query$("What action to take (Tile, Cascade, or New) on MDI
Windows?"), 1))
SWITCH Text
CASE "T"
TileWindow()
CASE "C"
CascadeWindow()
CASE "N"
NewWindow()
default
Message("Only the proposed options are available.")
ENDSWITCH
END FUNCTION

See also:

    NewWindow
    NextWindow
    SelectWindow
    TileWindow


ΓòÉΓòÉΓòÉ 42. Center ΓòÉΓòÉΓòÉ

This function turns centering on or off. This function toggles the current
state of the centering attribute. This function is equivalent to choosing Text
Alignment Center.


Syntax
Center()

Return Value
 1 (TRUE) if the text was centered, or if centering was removed.
-2 (GeneralFailure) if the alignment was not changed.

Example
FUNCTION Example()
text = Query$("Enter some text:")
New("_default.sty", 0, 0)      'open a new file
TYPE("{text}")
TYPE("[enter]")
TYPE("[ctrlhome][ctrlshiftend]")
Copy() 'copy text to clipboard
FOR I = 1 to 10
    Paste()   'paste text 10 times
NEXT
Message("The text will be shaded, bolded, italicized, underlined, and
centered.")
TYPE("[ctrlhome][ctrlshiftend]")
Bold()
Italic()
Underline()
Center()
TYPE("[ctrlhome]")
END FUNCTION

See also:

    Justify
    LeftAlign
    NormalText
    RightAlign




ΓòÉΓòÉΓòÉ 43. ChangeCascadeAction ΓòÉΓòÉΓòÉ

This function changes the action of the selected cascade menu item.


Syntax
ChangeCascadeAction(BarID, Menu, CascadeMenu, Item, NewAction, Help)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu this cascade menu rests on. This must
match exactly the name of the pull down menu you are referencing, including any
ampersand (&) characters in the name of the menu. An ampersand is placed before
a character that has an underline.
CascadeMenu is the name of the Cascade menu that the item to change is on. This
must match exactly the name of the cascade menu that the item to change is on,
including any ampersands (&).
Item is the name of the cascade menu item to be changed. If the menu item has a
shortcut key, you must press TAB, type a ^, and then type the appropriate
letter as part of the item name.
NewAction can either be an Ami Pro function or a macro.
Help is the one-line Help text that appears in the title bar of Ami Pro when
this menu item is highlighted. This parameter is not optional for this
function.

Return Value
1  (TRUE) if the item's action was changed.
0  (FALSE) if the change could not be made.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$() 'get the name of this macro
'change the Edit/Insert/Note text to say Hello World
ChangeCascadeAction(1, "&Edit", "&Insert", "&Note", "{MacFile}!Test()", "")
END FUNCTION

FUNCTION Test()
Message("Hello World...")
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    ChangeMenuAction
    CheckMenuItem
    GrayMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    RenameMenuItem


ΓòÉΓòÉΓòÉ 44. ChangeIcons ΓòÉΓòÉΓòÉ

This function changes the current icon set to the icon set specified in the
Name parameter. This function is equivalent to choosing Tools SmartIcons or the
SmartIcons button on the status bar and specifying the desired icon set.


A macro must be edited to insert this non-recordable function.

Syntax
ChangeIcons(Name)
Name is the name of the icon set. This is the full icon set name, not the file
name.
A null string ("") changes the current set to the default icon set.

Return Value
This function returns a 1.

Example
FUNCTION Example()
ChangeIcons("Working Together")
END FUNCTION

See also:

    GetIconPalette
    IconBottom
    IconCustomize
    IconFloating
    IconLeft
    IconRight
    IconTop
    SetIconSize


ΓòÉΓòÉΓòÉ 45. ChangeLanguage ΓòÉΓòÉΓòÉ

This function changes the default language path and sets the language used for
the current document and new documents. This function is equivalent to choosing
Tools Spell Check and choosing Language Options.


Syntax
ChangeLanguage(Path, NewLang, CurrentLang)
Path is the full path where the dictionary file is located.
NewLang is the number of the language dictionary to use.
CurrentLang is the number of the language dictionary for this document.
Language numbers are:
    1- American English
    2 - British English
    3 - French
    4 - French Canadian
    5 - Italian
    6 - Spanish
    7 - German
    8 - Dutch
    9 - Norwegian
    10 - Swedish
    11 - Danish
    12 - Portuguese
    13 - Finnish
    14 - Medical
    15 - Swiss German
    16 - Greek
    17 - Brazilian
    18 - Australian
    19 - Polish
    20 - Russian
    21 - Catalan
    22 - Nynorsk
    23 - Voorkeur

Return Value
1  (TRUE) if the language was changed.
0  (UserCancel/FALSE) if the language dictionary could not be changed or if the
user canceled the function.

Example
FUNCTION Example()
' get the path for the dictionary from the amiuser3.ini
path = GetProfileString$("AmiPro", "dictionary", "amiuser3.ini")
newlang = 7       'German
currlang = 1  'American English
ChangeLanguage(path, newlang, currlang)
END FUNCTION

See also:

    SpellCheck
    Thesaurus


ΓòÉΓòÉΓòÉ 46. ChangeMenuAction ΓòÉΓòÉΓòÉ

This function changes the function of a menu item on a pull down menu.


Syntax
ChangeMenuAction(BarID, Menu, Item, MacroName[!Function[(parm1[, parm2...])]][,
Help])
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu on which the item is located. This name
must match the name of the pull down menu, including any ampersand (&)
characters. An ampersand is placed before a character that has an underline.
Item is the name of the existing menu item to change. This name must match the
name of the existing menu item, including any ampersand (&) characters. An
ampersand is placed before a character that has an underline.
MacroName is the name of the Ami Pro function or macro to run if this menu item
is selected. This parameter may contain the macro file name, the function
within that file to call, and any parameters that function may require. At a
minimum, this parameter must contain the macro file name.
Help is the one-line Help text that appears in the title bar of Ami Pro when
this menu item is highlighted. If an Ami Pro function is used, its one-line
Help appears.

Return Value
A positive number if the menu item was changed.
0  (FALSE) if the menu item could not be changed, or if an invalid BarID or
MenuName was used.

Example
FUNCTION Example()
RMac = GetRunningMacroFile$() ' get the name of the running macro
ChangeMenuAction(1, "Too&ls", "Smart&Icons...", IconLeft, "Places the SmartIcon
bar on the left") ' make the menu toggle the icon bar
OnCancel RestoreIt ' set a goto address in case the user cancels
UserControl("Try out the SmartIcon menu item then select Resume") ' try it out
RestoreIt:
' change the menu
ChangeMenuAction(1, "Too&ls", "Smart&Icons...", IconCustomize, "Customize
SmartIcons by specifying the desired position, size and set of icons")
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    ChangeCascadeAction
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    DeleteMenuItem
    GetMacPath$
    GrayMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    RenameMenuItem



ΓòÉΓòÉΓòÉ 47. ChangeShortcutKey ΓòÉΓòÉΓòÉ

This function assigns a shortcut key combination to run a macro. It overrides
an existing macro key definition. It does not check to make sure that the
MacroName exists. If an invalid MacroName is used, the keystroke does nothing
when pressed.


Syntax
ChangeShortcutKey(MacroName, Key, State)
MacroName is the name of the macro, including the file name that should be
assigned to a keystroke.
Key is the alphanumeric function key used as the shortcut key combination.
State is the shift state of the key. It can be "C" (Control key), "S" (Shift
key), "A" (Alternate key), or a combination of the three.
You can use either CTRL or SHIFT, or a combination of the two, with most keys.
When assigning a shortcut, you must spell out the shortcut command keys. For
example, to assign SHIFT+F2, you must type the actual alphanumeric characters
with no spaces. You cannot use F10, SHIFT+F1, or SHIFT+ an alphanumeric key.

Return Value
1  (TRUE) if the macro was successfully assigned to the function key.
-2  (GeneralFailure) if the key could not be assigned because an invalid
keyname was used.

Example
FUNCTION Example()
FileName = Query$("What macro do you want to change the shortcut key for?")
Key = Query$("What number function key do you want to assign?")
IF not IsNumeric(Key)
    Message("Not a valid function key; try again.")
ENDIF
IF Decide("Use Shift with F{key}?")
    State = "S"
ELSE
    State = ""
ENDIF
IF Decide("Use Ctrl with F{key}?")
    State = strcat$(State, "C")
ENDIF
IF Decide("Use Alt with F{key}?")
    State = strcat$(State, "A")
ENDIF
RealKey=strcat$("F", Key)
IF -2 = ChangeShortcutKey(Filename, RealKey, State)
    Message("Could not change shortcut key for {Filename} to {State}F{Key}")
ENDIF
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    ChangeMenuAction
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    OnKey



ΓòÉΓòÉΓòÉ 48. CharLeft ΓòÉΓòÉΓòÉ

This function scrolls the document left one character without moving the
insertion point. This function is equivalent to clicking once on the right
arrow at the right of the horizontal scroll bar.


Syntax
CharLeft()

Return Value
This function returns 0.

Example
FUNCTION Example()
Again:
UserControl("Click Resume to shift to the left, or Cancel to Quit.")
CharLeft()
GoTo Again
END FUNCTION

See also:

    CharRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 49. CharRight ΓòÉΓòÉΓòÉ

This function scrolls the document right one character without moving the
insertion point. This function is equivalent to clicking once on the left arrow
at the left of the horizontal scroll bar.


Syntax
CharRight()

Return Value
This function returns 0.

Example
FUNCTION Example()
Again:
UserControl("Click Resume to shift to the right, or Cancel to Quit.")
CharRight()
GoTo Again
END FUNCTION

See also:

    CharLeft
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 50. CheckMenuItem ΓòÉΓòÉΓòÉ

This function adds or removes a check mark next to a menu item. Use this
function to indicate that the menu function is currently active.


You can only place indicators next to menu items you create.

Syntax
CheckMenuItem(BarID, Menu[, CascadeMenu], Item, State)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu that the item to be checked or unchecked
rests on. This must match exactly the name of the pull down menu you want to
modify, including any ampersand (&) characters. An ampersand is placed before a
character that has an underline.
CascadeMenu is the optional name of the cascade menu that the item to be
checked or unchecked rests on. This must match exactly the name of the cascade
menu you want to modify, including any ampersand (&) characters.
Item is the name of the menu item you want to check or uncheck. If the menu
item has a shortcut key, you must press TAB, type a ^, and then type the
appropriate letter as part of the item name.
State indicates whether the item is checked or unchecked. State can be either a
1 (On) or a 0 (Off).

Return Value
1  (TRUE) if the item was successfully checked or unchecked.
0  (FALSE) if the item could not be checked or unchecked, or if an invalid
BarID, MenuName, or ItemName was used.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()   'get the name of this macro
State = 0
DeleteMenuItem(1, "&Text", "B&old+Italic+Underline")
InsertMenuItem(1, "&Text", 10, "B&old+Italic+Underline", "{MacFile}!Example2(
{State})", "Bold and Italicize and Underline Text.")
END FUNCTION

FUNCTION Example2(State)
MacFile = GetRunningMacroFile$()
' This is the most important line in the macro
' it handles the toggle feature passed as the parameter State
' by making zero into one, one into zero.
State = Right$((State - 1), 1)
Bold(State)
Underline(State)
Italic(State)
ChangeMenuAction(1, "&Text", "B&old+Italic+Underline", "{MacFile}!Example2(
{State})", "Bold and Italicize and Underline Text.")
CheckMenuItem(1, "&Text", "B&old+Italic+Underline", State)
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    ChangeCascadeAction
    ChangeMenuAction
    ChangeMenuItem
    DeleteMenu
    DeleteMenuItem
    GrayMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu
    RenameMenuItem



ΓòÉΓòÉΓòÉ 51. CHR ΓòÉΓòÉΓòÉ

This function determines the code page character of the number provided.


Syntax
CHR$(Value)
Value is a number between 0 and 255.

Return Value
A single character string that is the code page character derived from the
function's argument.

Example
FUNCTION Example()
TYPE("NumberCharacter[Enter]")
FOR I = 1 to 255
    Char = CHR$(I)
    TYPE("{I}={Char}[Enter]")
NEXT
END FUNCTION

See also:

    ASC
    Instr
    LCASE$
    Left$
    MID$
    Right$
    strcat$
    strchr
    strfield$
    UCASE$



ΓòÉΓòÉΓòÉ 52. CleanScreenOptions ΓòÉΓòÉΓòÉ

This function determines which elements display in Clean Screen mode. This
function is equivalent to choosing View View Preferences and choosing Clean
Screen.


Syntax
CleanScreenOptions(Options)
Options is a flag that determines the screen elements to display. The Options
parameter can be one of the following:
    None (0) - None of the elements display.
    TitleBar (1) - Display the title bar. This value must be combined with
    MenuBar (2).
    MenuBar (2) - Display the menu bar.
    Icons (4) - Display the SmartIcons.
    StatusBar (8) - Display the status bar.
    VertScroll (16) - Display the vertical scroll bar.
    HorzScroll (32) - Display the horizontal scroll bar.
    ReturnIcon (64) - Display the icon to exit Clean Screen mode.
You can add the values together to get the Options parameter.

Return Value
This function returns 1.

Example
FUNCTION Example()
CleanScreenOptions(112)  ' Display the scroll bars and return icon
ToggleCleanScreen()
END FUNCTION

See also:

    ToggleCleanScreen
    ViewPreferences


ΓòÉΓòÉΓòÉ 53. ConnectCells ΓòÉΓòÉΓòÉ

This function connects or disconnects the selected table cells. This function
is equivalent to choosing Table Connect Cells. The ConnectCells function is a
toggle. If the selected cells are not connected, they become connected. If the
selected cells are already connected, they become disconnected.


Syntax
ConnectCells()

Return Value
1  (TRUE) if the cells were successfully connected or disconnected.
-2  (GeneralFailure) if the cells could not be connected or disconnected.
-7  (CouldNotFind) if the cells to connect or disconnect could not be located.

Example
FUNCTION Example()
DEFSTR StartRow, StartCol, EndRow, EndCol;
Tables(1, TRUE, 4, 10)
WHILE StartRow != 2
    TYPE("[Right]")
    TableGetRange(&StartRow, &StartCol, &EndRow, &EndCol)
WEND
TYPE("[ShiftRight][ShiftRight]")
ConnectCells()
TableLines(AllSides, 0, 0, OnePoint, 0)
END FUNCTION

See also:

    ProtectCells
    SizeColumnRow
    TableLayout
    TableLines
    Tables



ΓòÉΓòÉΓòÉ 54. Copy ΓòÉΓòÉΓòÉ

This function copies the selected text, selected frame, or table to the
clipboard. This function is equivalent to choosing Edit Copy.


Syntax
Copy()

Return Value
 1  (TRUE) if the text was copied to the clipboard.
-2  (GeneralFailure) if the text could not be copied or if there was no text to
copy.

Example
FUNCTION Example()
TYPE("Hello World")
TYPE("[CtrlHome][CtrlShiftEND]")
Copy()
Paste()
Paste()
END FUNCTION

See also:

    CurChar$
    CurShade$
    CurWord$
    Cut
    DDELinks
    Paste



ΓòÉΓòÉΓòÉ 55. CreateDataFile ΓòÉΓòÉΓòÉ

This function creates a new data file. It does not run the automated data file
record entry function.


Syntax
CreateDataFile()

Return Value
This function returns 1.

Example
FUNCTION Example()
CreateDataFile()
END FUNCTION

See also:

    CreateDescriptionFile
    Merge
    MergeToFile
    OpenDataFile
    OpenMergeFile



ΓòÉΓòÉΓòÉ 56. CreateDescriptionFile ΓòÉΓòÉΓòÉ

This function creates an Ami Pro merge description file. A description file
contains a list of the fields in an external data file. This function is
equivalent to entering the field names in the Merge Data File Fields dialog
box.


Syntax
CreateDescriptionFile(FileName, Type[, Fields...])
FileName is the name of the description file, in Ami Pro format, to be created.
Type is the format of the data file and is one of the following:
    Ami Pro
    1-2-3
    1-2-3 rel 3
    Comma delimited
    dBase
    DIF
    Excel
    Excel 3.0
    Excel 4.0
    Fixed length ASCII
Fields are the names of the fields to insert into the description file. You can
insert a maximum of 15 fields.

Return Value
This function returns 1.

Example
FUNCTION Example()
' this a description file with the name 123desc.sam with the following lines
CreateDescriptionFile("123desc.sam", "1-2-3 rel 3", "Name", "Address", "City",
"State", "Zip")
END FUNCTION

See also:

    CreateDataFile
    MergeToFile
    OpenDataFile
    OpenMergeFile


ΓòÉΓòÉΓòÉ 57. CreateStyle ΓòÉΓòÉΓòÉ

This function creates a new paragraph style. This function is equivalent to
choosing Style Create Style.


The paragraph style name cannot exceed thirteen characters.

Syntax
CreateStyle(NewName, BaseName, Options)
NewName is the name of the new paragraph style.
BaseName is the name of the existing paragraph style on which to base the new
paragraph style.
Options is a flag which determines whether to create or modify a style. It also
determines whether to create or modify a style based on the style at the
insertion point position or in the BaseName parameter.
    CreateSty (0) - Create style
    ModSty (1) - Modify style
    SelectSty (2) - Create or modify style based on the style at the insertion
    point position. If this parameter is used, the BaseName parameter is
    ignored. You must still enter an empty string ("") for the BaseName.
The Options parameter must use either CreateSty or ModSty. SelectSty may be
added to one of the other parameters.

To display the Create Styles dialog box and allow the user to select the new
paragraph style name and the paragraph style it is based on: CreateStyle

Return Value
1  (TRUE) if the new paragraph style was created.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the paragraph style could not be created.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable
    SaveAsNewStyle
    StyleManagement


ΓòÉΓòÉΓòÉ 58. CurChar ΓòÉΓòÉΓòÉ

This function is used to determine the character to the right of the insertion
point.


Syntax
CurChar$()

Return Value
The character to the right of the insertion point.
The null string ("") if there is a mark at the insertion point. Marks returning
the null string include a bookmark, a note, a date mark, a merge variable, the
end of a paragraph, a footnote, etc.

Example
FUNCTION Example()
UserControl("Place your cursor in the document, then click Resume...")
Message(CurChar$())
UserControl("Shade some text, then click Resume...")
Message(CurShade$())
UserControl("Double-click a word in your document, then click Resume...")
Message(CurWord$())
END FUNCTION

See also:

    CurShade$
    CurWord$
    GetMarkText$
    GetTextBeforeCursor$
    GoToCmd



ΓòÉΓòÉΓòÉ 59. CurShade ΓòÉΓòÉΓòÉ

This function is used to obtain the value of the selected text.


Syntax
CurShade$()

Return Value
The null string ("") if there is no text selected.
Only printable characters are returned. Marks in the text are ignored.

Example
FUNCTION Example()
UserControl("Place your cursor in the document, then click Resume...")
Message(CurChar$())
UserControl("Shade some text, then click Resume...")
Message(CurShade$())
UserControl("Click a word in your document, then click Resume...")
Message(CurWord$())
END FUNCTION

See also:

    CurChar$
    CurWord$
    GetMarkText$
    GetTextBeforeCursor$
    GoToCmd



ΓòÉΓòÉΓòÉ 60. CurWord ΓòÉΓòÉΓòÉ

This function is used to obtain the value of the word at the insertion point.


Syntax
CurWord$()

Return Value
Only printable characters. Marks in the text are ignored.

Example
FUNCTION Example()
UserControl("Place your cursor in the document, then click Resume...")
Message(CurChar$())
UserControl("Shade some text, then click Resume...")
Message(CurShade$())
UserControl("Click a word in your document, then click Resume...")
Message(CurWord$())
END FUNCTION

See also:

    CurChar$
    CurShade$
    GetMarkText$
    GetTextBeforeCursor$
    GoToCmd




ΓòÉΓòÉΓòÉ 61. CustomView ΓòÉΓòÉΓòÉ

This function changes the current view level to Custom View. This function is
equivalent to choosing View Custom.


Syntax
CustomView()

Return Value
This function returns 1.

Example
FUNCTION Example()
CustomView()
END FUNCTION

See also:

    EnlargedView
    FacingView
    FullPageView
    GetViewLevel
    LayoutMode
    StandardView


ΓòÉΓòÉΓòÉ 62. Cut ΓòÉΓòÉΓòÉ

This function is used to cut the selected text, frame, or table from the
document and save it to the clipboard. This function is equivalent to choosing
Edit Cut.


Syntax
Cut()

Return Value
This function does not return a value. If no text was shaded, the macro
terminates with an error message.

Example
FUNCTION Example()
UserControl("Shade the text to move to the end of the doc, then click
Resume...")
Cut()      ' cut the selected text
TYPE("[CtrlEND]")    ' move to the end of the file
Paste()       ' paste the text at the end of the file
END FUNCTION

See also:

    Copy
    CurChar$
    CurShade$
    CurWord$
    DDELinks
    Paste


ΓòÉΓòÉΓòÉ 63. DateDiff ΓòÉΓòÉΓòÉ

This function takes two dates (Date1, Date2) and calculates the number of days
elapsed by subtracting Date2 from Date1.


Syntax
DateDiff(Date1, Date2)
Date1 is the first date to examine. It can be stated as the number of seconds
since January 1, 1970 or the current OS/2 date format.
Date2 is the second date to examine. It can be stated as the number of seconds
since January 1, 1970 or the current OS/2 date format.
The date format must match the separator and month, day, and year order found
in the OS/2 System Setup Country settings.

Return Value
The number of days the two dates differ.

Example
FUNCTION Example()
Born = Query$("What is your Birthday (MM/DD/YY)?")
Date = FormatDate$(Now(), "h") 'current date
Time = FormatTime$(Now(), 6)   'current time
Days = DateDiff(Born, Date) ' how many days old
TextDate = FormatDate$(Now(), "d")    'format the date
Message("It is now {Time} on {TextDate}. You are {Days} days old.")
END FUNCTION

See also:

    FormatDate$
    FormatTime$
    GetTime
    Now


ΓòÉΓòÉΓòÉ 64. DDEAdvise ΓòÉΓòÉΓòÉ

This function is used to have another application notify Ami Pro when data has
changed in that application. Before using the DDEAdvise function, a
conversation with the other application must be started using the DDEInitiate
function.


Following the DDEAdvise function, Ami Pro continues operation normally. When
data is received from the channel and item, the macro specified in the
DDEAdvise function is started. The data received from the other application (in
CF_Text format) is passed to the macro specified in the DDEAdvise function as
the first argument to the macro. It is up to the macro to parse the data from
the other application as needed.

Syntax
DDEAdvise(ChannelID, Item, MacroName[!Function])
ChannelID is the channel ID of the Dynamic Data Exchange (DDE) conversation.
Item describes the information requested from the linked application.
MacroName is the name of an Ami Pro macro to execute when data changes in the
linked application.

Return Value
1  (TRUE) if the other application responded to the Ami Pro request.
0  (FALSE) if the other application could not be contacted or if an invalid
ChannelID was used.

Example
FUNCTION Example()
' This example starts a conversation with 123w untitled worksheet and
' sets up a dde advise back to Ami Pro with the cells A1 and A2.

' If the user types data into A1, Ami Pro is notified and displays the value.
' If the user types data into A2, Ami Pro breaks the Advise with DDEUnAdvise
' and terminates the conversation.

id = DDEInitiate("123w", "Untitled") ' start a dde conversation with 123w
IF id = 0
    Exec("c:\123w\123w.exe", "") ' launch app if unable to connect
    id = DDEInitiate("123w", "Untitled") ' contact one more time
    IF id = 0
       Message("Unable to contact server application.") ' failed to contact
       EXIT FUNCTION
    ENDIF
ENDIF
AllocGlobalVar("ChannelID", 1) ' create a global variable
SetGlobalVar("ChannelID", id) ' store the channel id in a global variable
RMac = GetRunningMacroFile$() ' what macro name are we running?
DDEAdvise(id, "A1", "{RMac}!GetData") ' set up advise for cell A1
DDEAdvise(id, "A2", "{RMac}!EndDDE") ' set up advise for cell A2
END FUNCTION

Function GetData(value)
Message("The value just typed in A1 = {value}") ' display the value
END FUNCTION

Function EndDDE()
id = GetGlobalvar$("ChannelID") ' get the channel id
DDEUnAdvise(id, "A1") ' unadvise on both cells
DDEUnAdvise(id, "A2")
DDETerminate(id) ' terminate the dde conversation
FreeGlobalVar("ChannelID") ' free the global variable
Message("DDE Session Terminated!") ' let the user know it worked
END FUNCTION

See also:

    DDEExecute
    DDEInitiate
    DDEPoke
    DDEReceive$
    DDETerminate
    DDEUnAdvise
    Exec
    GetMacPath$
    GetRunningMacroFile$



ΓòÉΓòÉΓòÉ 65. DDEExecute ΓòÉΓòÉΓòÉ

This function gives a command to an application using Dynamic Data Exchange
(DDE). Before using this function, a conversation with the other application
must be started using the DDEInitiate function. The command given to the linked
application is defined by that application.


Syntax
DDEExecute(ChannelID, Command)
ChannelID is the channel ID of the DDE conversation.
Command is the command, in square brackets, to give to the linked application.

Return Value
0  if the command was successfully sent to the other application.
-1 if the application refused the command or if an invalid ChannelID was used.

Example
FUNCTION Example()
' This example commands 123w to open the file EMPLOYEE.WK3

' start a dde conversation with 123w
id = DDEInitiate("123w", "Untitled")
IF id = 0
    ' launch app if unable to connect
    Exec("c:\123w\123w.exe", "")
    ' contact one more time
    id = DDEInitiate("123w", "Untitled")
    IF id = 0
       ' failed to contact
       Message("Unable to contact server application.")
       EXIT FUNCTION
    ENDIF
ENDIF
onerror endit ' set up an error address
filename = "Employee.wk3" ' assign a file to a variable
' assign a command to a variable
command = "[[RUN(""/FR{filename}~"")]"
DDEExecute(id, command) ' command 123w to execute the command
endit:
DDETerminate(id) ' terminate the conversation
END FUNCTION

See also:

    ActivateApp
    DDEAdvise
    DDEInitiate
    DDEPoke
    DDEReceive$
    DDETerminate
    DDEUnAdvise
    Exec


ΓòÉΓòÉΓòÉ 66. DDEInitiate ΓòÉΓòÉΓòÉ

This function starts a conversation with another application using Dynamic Data
Exchange (DDE). The application must be capable of communicating using the DDE
protocol. This function must be used prior to any other DDE activity with an
application.


Syntax
DDEInitiate(App, Data)
App is the application that is the target of the DDE conversation.
Data is defined by the other application, but usually is the name of the
application's data file you want to access.

Return Value
A positive number if the ChannelID of the conversation was successfully
established.
0  (FALSE) if the conversation could not be started. This was because the
application was not running, did not have the Topic open, or does not support
DDE.

Example
FUNCTION Example()
Mac = GetRunningMacroFile$()
id = DDEInitiate("123W", "Untitled")
IF id = 0
    Exec("123W.EXE","") ' No id, try to start 123W
    id = DDEInitiate("123W", "Untitled")
       IF id = 0
           Message("Could not initiate a conversation with 1-2-3!")
           Exit Function
       ENDIF
ENDIF
' Poke data into spreadsheet
Address = "A2"    ' This could be a named range
Value = 30
DDEPoke(id,Address,Value)
DDEPoke(id, "A1", "200")
DDETerminate(Id)  ' Terminate the conversation
END FUNCTION

See also:

    DDEAdvise
    DDEExecute
    DDEPoke
    DDEReceive$
    DDETerminate
    DDEUnAdvise
    Exec



ΓòÉΓòÉΓòÉ 67. DDELinks ΓòÉΓòÉΓòÉ

This function displays the Link Options dialog box. This function is equivalent
to choosing Edit/Link Options. Links cannot be adjusted automatically using a
macro. When the dialog box displays, the user can view and adjust them manually
and then choose Update or Cancel to return to the macro.


Syntax
DDELinks(Flag, Count[, LinkSpecPairs][, App, Data, Item])
Flag is the action taken.
    1 - Unlink
    2 - Update
    3 - Stop
    4 - Change
    5 - Create
    Create is probably the most commonly used value.
Count is the number of LinkSpecPairs. Each pair consists of the internal ID and
the Type (text or frame).

Return Value
1  (TRUE) if the  links dialog box was successfully displayed.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
' this command was initiated with a DDE link from cell A2 in a 1-2-3
' file called FILE0001.WK3 into an Ami Pro document
' called TESTFILE.SAM.This document was opened and initially DDE links
' were not updated.

flag=2 'update link
numlinks=1 'number of link to change with this statement
whichlink=1   'the number of the link to change
linktype="Text"   'the kind of link to change
DDELinks(flag, numlinks, whichlink, linktype)
END FUNCTION

See also:

    Copy
    Cut
    Paste


ΓòÉΓòÉΓòÉ 68. DDEPoke ΓòÉΓòÉΓòÉ

This function is used to send data from Ami Pro to another application or to a
bookmark. Before using this function, a conversation with the other application
must be started using the DDEInitiate function.


If you name an existing text bookmark in a DDEPoke message, Ami Pro replaces
the contents of the bookmark with the poked data.

Syntax
DDEPoke(ChannelID, Location, Data)
ChannelID is the channel ID of the Dynamic Data Exchange (DDE) conversation.
Location is the location in the other application to poke the data or the name
of the bookmark.
Data is the data to send to the other application.

Return Value
1  (TRUE) if the other application accepted the data sent by Ami Pro.
0  (FALSE) if the other application could not be contacted or if an invalid
ChannelID was used.

Example
FUNCTION Example()
Mac = GetRunningMacroFile$()
id = DDEInitiate("123W", "Untitled")
IF id = 0
    ' No id, try to start 123W
    Exec("123W.EXE","")
    id = DDEInitiate("123W", "Untitled")
       IF id = 0
           Message("Could not initiate a conversation with 1-2-3!")
           Exit Function
       ENDIF
ENDIF

' Poke data into spreadsheet
Address = "A2"    ' This could be a named range
Value = 30
DDEPoke(id,Address,Value)
DDEPoke(id, "A1", "200")
DDETerminate(Id)  ' Terminate the conversation
END FUNCTION

See also:

    DDEAdvise
    DDEExecute
    DDEInitiate
    DDEReceive$
    DDETerminate
    DDEUnAdvise
    Exec


ΓòÉΓòÉΓòÉ 69. DDEReceive ΓòÉΓòÉΓòÉ

This function receives up to 250 characters from an application using Dynamic
Data Exchange (DDE). Before using this function, a conversation with the other
application must be started using the DDEInitiate function. When this function
is used, Ami Pro waits until the other application processes the request and
then receives the data.


Syntax
DDEReceive$(ChannelID, Item)
ChannelID is the channel ID of the DDE conversation.
Item describes the information requested from the linked application.

Return Value
A null string ("") if the application could not send the data.
The data requested from the other application.

Example
FUNCTION Example()
id = DDEInitiate("123W", "Untitled")
IF id = 0
    Exec("C:\123W\123W.EXE", 1)
    FOR I = 1 to 10
       id = DDEInitiate("123W", "Untitled")
       IF id > 0
           OK = TRUE
           BREAK
       ENDIF
    NEXT
    IF not OK
       Message("Could not initiate a conversation with 1-2-3!")
       EXIT FUNCTION
    ENDIF
ENDIF
Principal = Query$("What is the principal of the loan?")
Interest = Query$("What is the annual interest rate (12% = .12)?") / 12
Term = Query$("What is the term in months?")
IF Interest > 1
    Interest = Interest / 100
ELSEIF Right$(Interest, 1) = "%"
    Interest = Left$(Interest, (Len(Interest) - 1)) / 100
ENDIF
DDEExecute(id, "[[RUN(""+@PMT({Principal},{Interest},{Term})~"")]")
Value = DDEReceive$(id, "A1")
DDETerminate(id)
Message(Value)
END FUNCTION

See also:

    DDEAdvise
    DDEExecute
    DDEInitiate
    DDEPoke
    DDETerminate
    DDEUnAdvise
    Exec


ΓòÉΓòÉΓòÉ 70. DDETerminate ΓòÉΓòÉΓòÉ

This function ends a conversation with an application using Dynamic Data
Exchange (DDE). When this function is used, Ami Pro closes the link with the
other application. If more information is needed after this function is used, a
new conversation must be started.


Syntax
DDETerminate(ChannelID)
ChannelID is the channel ID of the DDE conversation.

Return Value
1  (TRUE) if the conversation was successfully concluded.
0  (FALSE) if the conversation was not concluded or if an invalid ChannelID was
used.

Example
FUNCTION Example()
Mac = GetRunningMacroFile$()
id = DDEInitiate("123W", "Untitled")
IF id = 0
    ' No id, try to start 123W
    Exec("123W.EXE","")
    id = DDEInitiate("123W", "Untitled")
       IF id = 0
           Message("Could not initiate a conversation with 1-2-3!")
           Exit Function
       ENDIF
ENDIF

' Poke data into spreadsheet
Address = "A2"    ' This could be a named range
Value = 30
DDEPoke(id,Address,Value)
DDEPoke(id, "A1", "200")
DDETerminate(Id)  ' Terminate the conversation
END FUNCTION

See also:

    DDEAdvise
    DDEExecute
    DDEInitiate
    DDEPoke
    DDEReceive$
    DDEUnAdvise
    Exec


ΓòÉΓòÉΓòÉ 71. DDEUnAdvise ΓòÉΓòÉΓòÉ

This function is used to reset the notification status set up using the
DDEAdvise function. When this function is used, the other application on the
current Dynamic Data Exchange (DDE) channel no longer notifies Ami Pro when
data changes have occurred.


Syntax
DDEUnAdvise(ChannelID, Item)
ChannelID is the channel ID of the DDE conversation.
Item describes the information requested from the linked application.

Return Value
1  (TRUE) if the other application responded to the Ami Pro request.
0  (FALSE) if the other application could not be contacted or if an invalid
ChannelID was used.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
DECLARE GetNumber()
id = DDEInitiate("123W", "Untitled")
IF id = 0
    Exec("123W.EXE", 1)
    FOR I = 1 to 10
       id = DDEInitiate("123W", "Untitled")
       IF id > 0
           OK = TRUE
           BREAK
       ENDIF
    NEXT
    IF not OK
       Message("Could not initiate a conversation with 1-2-3!")
       EXIT FUNCTION
    ENDIF
ENDIF
AllocGlobalVar("ChannelNumber", 1)
SetGlobalVar("ChannelNumber", id)
DDEPoke(id, "A1", "12345")
DDEAdvise(id, "A1", "{MacFile}!GetNumber")
GoTo endit
toast:
DDEUnAdvise(id, "A1")
FreeGlobalVar("ChannelNumber")
DDETerminate(id)
endit:
END FUNCTION

FUNCTION GetNumber()
id = GetGlobalVar$("ChannelNumber")
FreeGlobalVar("ChannelNumber")
Value = DDEReceive$(id, "A1")
DDEUnAdvise(id, "A1")
DDETerminate(id)
Message("The contents of cell A1 is {Value}")
END FUNCTION

See also:

    DDEAdvise
    DDEExecute
    DDEInitiate
    DDEPoke
    DDEReceive$
    DDETerminate
    Exec


ΓòÉΓòÉΓòÉ 72. Decide ΓòÉΓòÉΓòÉ

This function displays a standard message box with a Help button, the specified
prompt and title, and Yes and No push buttons. It waits for the user to select
a push button and then returns the ID of the button pressed.


Syntax
Decide(Prompt[, Title])
prompt is a string used as a prompt to the user. It can be a maximum of 80
characters.
Title is the title for the message box. The default is "Ami Pro Macro."

Return Value
    DecideYes (1) - Yes
    DecideNo (0) - No

Example
FUNCTION Example()
again:
result = Decide("See this message again?")
IF result = 1
    GoTo again
ENDIF
END FUNCTION

See also:

    DialogBox
    Message
    Query$
    UserControl


ΓòÉΓòÉΓòÉ 73. DefineStyle ΓòÉΓòÉΓòÉ

This function takes the attributes of the selected text and applies it to the
currently selected style. This function is equivalent to choosing Style Define
Style.


Syntax
DefineStyle()

Return Value
1  (TRUE) if the style was changed.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
' Type some text and apply an attribute
Type ("This is some text")
Type ("[ShiftCtrlLeft]")    ' Shade one word
Bold()
Italic()
DefineStyle()     ' Apply the attributes to the current style
END FUNCTION

See also:

    CreateStyle
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable
    SaveAsNewStyle
    StyleManagement




ΓòÉΓòÉΓòÉ 74. DeleteColumnRow ΓòÉΓòÉΓòÉ

This function deletes a column or row from a table. This function is equivalent
to choosing Table Delete Column Row.


Syntax
DeleteColumnRow(Which)
Which determines whether to delete the current column or the current row. This
parameter should be set to one of the following values:
    Column (1) - Delete the current column
    Row (0) - Delete the current row

To display a dialog box that allows the user to decide whether to delete a
column or row: DeleteColumnRow

Return Value
1  (TRUE) if the column or row was deleted.
0  (UserCancel/FALSE) if the user canceled the function or if no action was
taken.

Example
FUNCTION Example()
DeleteColumnRow(Column)
END FUNCTION

See also:

    InsertColumnRow
    SizeColumnRow



ΓòÉΓòÉΓòÉ 75. DeleteEntireTable ΓòÉΓòÉΓòÉ

This function deletes the selected table. This function is equivalent to
choosing Table Delete Entire Table.


Syntax
DeleteEntireTable()

Return Value
0  (NoAction) if no action is taken. The table may not exist or may not be
selected.
1  (True) if the table is deleted.
-2  (GeneralFailure) if the function failed.

Example
FUNCTION Example()
DeleteEntireTable()
END FUNCTION

See also:

    DeleteColumnRow
    InsertColumnRow
    SizeColumnRow
    TableLayout
    TableLines
    Tables


ΓòÉΓòÉΓòÉ 76. DeleteMenu ΓòÉΓòÉΓòÉ

This function deletes a menu from a menu bar.


Syntax
DeleteMenu(BarID, Menu)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu to be deleted. This name must match the
name of the pull down menu you want to delete, including any ampersand (&)
characters. An ampersand is placed before a character that has an underline.

Return Value
1  (TRUE) if the menu was successfully deleted.
0  (FALSE) if the menu could not be deleted or if an invalid BarID or Menu name
was used.

Example
FUNCTION Example()
' get the name of this macro
Mac = GetRunningMacroFile$()
Menu = "&Custom"
DeleteMenu(1,Menu)
AddMenu(1,Menu)   'Add a menu called Custom
' add menu items
AddMenuItem(1,Menu,"New...",New,"")
AddMenuItem(1,Menu,"My Copy",Copy,"")
AddMenuItem(1,Menu,"-","","")
AddMenuItem(1,Menu,"Remove {Menu}","{Mac}!Remove()","Remove {Menu} menu.")
End Function

Function Remove()
DeleteMenu(1,"&Custom")
END FUNCTION

See also:

    AddMenu
    AddMenuItem
    ChangeMenuAction
    CheckMenuItem
    DeleteMenuItem
    GrayMenuItem
    RenameMenuItem


ΓòÉΓòÉΓòÉ 77. DeleteMenuItem ΓòÉΓòÉΓòÉ

This function deletes a menu item from a menu or a cascade menu.


Syntax
DeleteMenuItem(BarID, Menu[, CascadeMenu], Item)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down where the item to be deleted is located. This
name must match the name of the pull down menu, including any ampersand (&)
characters. An ampersand is placed before a character that has an underline.
CascadeMenu is the optional name of the cascade menu where the item to be
deleted is located. This name must match the name of the cascade menu,
including any ampersand (&) characters. An ampersand is placed before a
character that has an underline.
ItemName is the name of the menu item to be deleted. This name must match. If
the menu item has a shortcut key, you must press TAB, type a ^, and then type
the appropriate letter as part of the item name.

Return Value
1 (TRUE) if the item was successfully deleted.
0 (FALSE) if the item could not be deleted or if an invalid BarID, MenuName, or
ItemName was used.

Example
FUNCTION Example()
RMac = GetRunningMacroFile$() ' get the name of the running macro
DeleteMenuItem(1, "&File", "&Print... ^P")
OnCancel RestoreIt ' set a goto address in case the user cancels
UserControl("The Print menu item is gone. Select Resume to restore.")
RestoreIt:
' put the the menu back
InsertMenuItem(1, "&File", 17, "&Print...    ^P", fileprint, "Print the current
 document.")
END FUNCTION

See also:

    AddMenu
    AddMenuItem
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    GrayMenuItem
    RenameMenuItem


ΓòÉΓòÉΓòÉ 78. DialogBox ΓòÉΓòÉΓòÉ

You can create a dialog box in the Dialog Editor by drawing push buttons, group
boxes, radio buttons, check boxes, text boxes, edit boxes, list boxes, combo
boxes, and static text directly onto an editing screen. After you create and
save your dialog box in the Dialog Editor, you can include it in or call it
from an Ami Pro macro.


The dialog box you create in the Dialog Editor is modal. That means the user
can make choices from the dialog box, but no other action can take place until
either OK or CANCEL has been chosen. You must include either an OK button, a
CANCEL button, or both in the dialog box to return control to the macro.

The exception to this is when you assign a callback to a particular control. If
the value of a control that has a callback assigned to it ever changes, then a
macro function specified in SetDialogCallback is instantly executed, even
though the dialog box is still displayed. This allows you to validate data
entered in a dialog box.

You can use FillList to supply the contents of a list box prior displaying the
dialog box. You can use FillEditto supply the contents of any edit box or list
box or to supply the state of a button prior to displaying the dialog box. Once
the dialog box display is complete, you can use GetDialogField$ to retrieve the
contents of the dialog box fields.

If you copy the dialog box into an Ami Pro macro, the formatting information
for the dialog box must be contained between the DIALOG and END DIALOG
statements.

Syntax
DialogBox(ResourceFile, DialogBoxName)
ResourceFile is the file name of the external file which contains the dialog
box, for example, SMARTFLD.DLG. If the dialog box was created using the Dialog
Editor and is the only dialog box in the file, this parameter should be the
null string (""). If the dialog box was created using the Dialog Editor and
resides in the currently running macro file, this parameter should be a period
(".").
DialogBoxName is the name of the dialog box to be accessed. If the dialog box
was created using the Dialog Editor and is the only dialog box in an external
file, this parameter should be set to the name of the file.

Return Value
The ID of the push button pressed.
0  (UserCancel) if the user canceled the function.
-1  (NotFound) if the resource file was not found.

Example
FUNCTION Example()
Filledit(20,1)       ' Turn apples on
Filledit(8000,"Bob") ' Put text in Edit Box
Filledit(9001,"*.sam")
Box = DialogBox(".","ExampleBox")
IF Box<>1
    EXIT FUNCTION
ENDIF
Store = GetdialogField$(22)    ' Retrieve Combo Box
File = GetdialogField$(9001)       ' Retrieve List Box result
Name = GetDialogField$(8000)   ' Retrieve Edit Box
Dir = GetCurrentDir$()      ' Get current directory
Message("Goto Store = {Store} Name = {Name} File = {File}")
END FUNCTION

DIALOG ExampleBox
-2134376448 10 71 44 115 98 "" "" "Sample Dialog Box"
FONT 8 "Helv"
69 3 40 14 1 1342373889 "button" "OK" 0
69 19 40 14 2 1342373888 "button" "Cancel" 0
6 24 52 56 9001 1352728579 "listbox" "" 0
6 13 40 10 7999 1342177280 "static" "" 0
6 4 40 10 1001 1342177280 "static" "&Files:" 0
69 37 37 12 20 1342242825 "button" "&Apples" 0
69 49 42 12 21 1342242825 "button" "&Oranges" 0
6 83 45 12 22 1342242819 "button" "&Goto Store" 0
69 61 42 12 23 1342242825 "button" "&Soap" 0
69 82 43 12 8000 1350631552 "edit" "" 0
END DIALOG

See also:

    Decide
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption
    FillEdit
    FillList
    GetDialogField$
    GetDLGItem
    GetDLGItemText
    GetMacPath$
    Message
    Query$
    SetDLGCallBack
    SetDLGItemText
    UserControl
    Using the Lotus Dialog Editor


ΓòÉΓòÉΓòÉ 79. DlgClearControl ΓòÉΓòÉΓòÉ

This function clears the specified control ID from list boxes, combo boxes, and
edit boxes that have been created using the Dialog Editor.


Syntax
DlgClearContro(Hdlg, ID)
Hdlg identifies the dialog box handle.
ID is the number the Dialog Editor automatically assigns to a control. An edit
box can have an ID value from 8000 through 8999. A list box can have an ID
value from 9000 through 9499. A combo box can have an ID value from 9500
through 9999.

Return Value

Example
Function Main()
Mac = GetRunningMacroFile$()
DocPath = GetDocPath$()
SetDlgCallBack(0, "{Mac}!InitDlg")
SetDlgCallBack(21, "{Mac}!ClearBox")
FillEdit(9001, "{DocPath}*.sam")
Box = DialogBox(".","OpenBox")
End Function

Function InitDlg(Hdlg)
' Init routine for the dialogbox - this is executed before the box is displayed
DlgEnableControl(Hdlg, 1, 0)       ' grey the OK button
End Function

Function ClearBox(Hdlg, id, value)
' hit the Clear button to get here
Message("Clear the listbox and enable the OK")
DlgEnableControl(Hdlg, 1, 1)
DlgClearControl(Hdlg, 9001)
Message("Now close the box")
DlgClose(Hdlg)
End Function

DIALOG OpenBox
-2134376448   4   71 51 160 90 ""  "" "Listbox Example"
10  10 85  40 9001   1352728579"listbox" ""  0
6   60 40  14 1   1342373889"button"  "OK"   0
54  60 40  14 2   1342373888"button"  "Cancel"  0
99  60 40  14 21  1342373888"button"  "Clear"0
END DIALOG

See also:

    DialogBox
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption




ΓòÉΓòÉΓòÉ 80. DlgClose ΓòÉΓòÉΓòÉ

This function closes a dialog box that has been created using the Dialog
Editor.


Syntax
DlgClose(Hdlg)
Hdlg identifies the dialog box handle.

Return Value

Example
Function Main()
Mac = GetRunningMacroFile$()
DocPath = GetDocPath$()
SetDlgCallBack(0, "{Mac}!InitDlg")
SetDlgCallBack(21, "{Mac}!ClearBox")
FillEdit(9001, "{DocPath}*.sam")
Box = DialogBox(".","OpenBox")
End Function

Function InitDlg(Hdlg)
' Init routine for the dialogbox - this is executed before the box is displayed
DlgEnableControl(Hdlg, 1, 0)       ' grey the OK button
End Function

Function ClearBox(Hdlg, id, value)
' hit the Clear button to get here
Message("Clear the listbox and enable the OK")
DlgEnableControl(Hdlg, 1, 1)
DlgClearControl(Hdlg, 9001)
Message("Now close the box")
DlgClose(Hdlg)
End Function

DIALOG OpenBox
-2134376448   4   71 51 160 90 ""  "" "Listbox Example"
10  10 85  40 9001   1352728579"listbox" ""  0
6   60 40  14 1   1342373889"button"  "OK"   0
54  60 40  14 2   1342373888"button"  "Cancel"  0
99  60 40  14 21  1342373888"button"  "Clear"0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption


ΓòÉΓòÉΓòÉ 81. DlgEnableControl ΓòÉΓòÉΓòÉ

This function enables or grays the specified control in list boxes, combo
boxes, and edit boxes that have been created using the Dialog Editor.


Syntax
DlgEnableControl(Hdlg, ID, Enable)
Hdlg identifies the dialog box handle.
ID is the number the Dialog Editor automatically assigns to a control. An edit
box can have an ID value from 8000 through 8999. A list box can have an ID
value from 9000 through 9499. A combo box can have an ID value from 9500
through 9999.
Enable is either 0 if you want to gray a specific control, or 1 if you want to
return the control to its normal state.

Return Value

Example
Function Main()
Mac = GetRunningMacroFile$()
DocPath = GetDocPath$()
SetDlgCallBack(0, "{Mac}!InitDlg")
SetDlgCallBack(21, "{Mac}!ClearBox")
FillEdit(9001, "{DocPath}*.sam")
Box = DialogBox(".","OpenBox")
End Function

Function InitDlg(Hdlg)
' Init routine for the dialogbox - this is executed before the box is displayed
DlgEnableControl(Hdlg, 1, 0)       ' grey the OK button
End Function

Function ClearBox(Hdlg, id, value)
' hit the Clear button to get here
Message("Clear the listbox and enable the OK")
DlgEnableControl(Hdlg, 1, 1)
DlgClearControl(Hdlg, 9001)
Message("Now close the box")
DlgClose(Hdlg)
End Function

DIALOG OpenBox
-2134376448   4   71 51 160 90 ""  "" "Listbox Example"
10  10 85  40 9001   1352728579"listbox" ""  0
6   60 40  14 1   1342373889"button"  "OK"   0
54  60 40  14 2   1342373888"button"  "Cancel"  0
99  60 40  14 21  1342373888"button"  "Clear"0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption


ΓòÉΓòÉΓòÉ 82. DlgGetListBoxCount ΓòÉΓòÉΓòÉ

This function returns the number of items in the specified list boxes, combo
boxes, and edit boxes that have been created using the Dialog Editor.


Syntax
DlgGetListBoxCoun(Hdlg, ID)
Hdlg identifies the dialog box handle.
ID is the number the Dialog Editor automatically assigns to a control. An edit
box can have an ID value from 8000 through 8999. A list box can have an ID
value from 9000 through 9499. A combo box can have an ID value from 9500
through 9999.

Return Value
The number of items in the specified list boxes, combo boxes, and edit boxes.

Example
Function Main()
Mac = GetRunningMacroFile$()
Dim Name(3)
Name(1) = "Charlie"
Name(2) = "Nancy"
Name(3) = "David"
SetDlgCallBack(21, "{Mac}!GiveInfo")
FillEdit(9000, &Name)
Box = DialogBox(".","Demo")
If Box <>1
    ' if cancel then exit the macro
    Exit Function
Endif
End Function

Function GiveInfo(Hdlg, id, value)
' hit the info button to get here
Count = DlgGetListBoxCount(Hdlg, 9000)
Item1 = DlgGetListBoxLine$(Hdlg, 9000, 0)    'index is zero based
Message("{Count} items in the listbox, item1 is {item1}")
End Function

DIALOG Demo
-2134376448   4   71 51 160 90 ""  "" "Listbox Example"
10  10 85  40 9000   1352728579"listbox" ""  0
6   60 40  14 1   1342373889"button"  "OK"   0
54  60 40  14 2   1342373888"button"  "Cancel"  0
99  60 40  14 21  1342373888"button"  "Info..." 0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption




ΓòÉΓòÉΓòÉ 83. DlgGetListBoxLines ΓòÉΓòÉΓòÉ

This function retrieves one entry from the specified list box that has been
created using the Dialog Editor.


Syntax
DlgGetListBoxLines$(hdlg, ID, Index)
Hdlg identifies the dialog box handle.
ID is the number the Dialog Editor automatically assigns to a control. A list
box can have an ID value from 9000 through 9499.
Index is the number of the item you want to retrieve. Index is 0 based, so the
first item is equal to 0, the second item is equal to one, etc.

Return Value

Example
Function Main()
Mac = GetRunningMacroFile$()
Dim Name(3)
Name(1) = "Charlie"
Name(2) = "Nancy"
Name(3) = "David"
SetDlgCallBack(21, "{Mac}!GiveInfo")
FillEdit(9000, &Name)
Box = DialogBox(".","Demo")
If Box <>1
    ' if cancel then exit the macro
    Exit Function
Endif
End Function

Function GiveInfo(Hdlg, id, value)
' hit the info button to get here
Count = DlgGetListBoxCount(Hdlg, 9000)
Item1 = DlgGetListBoxLine$(Hdlg, 9000, 0)    'index is zero based
Message("{Count} items in the listbox, item1 is {item1}")
End Function

DIALOG Demo
-2134376448   4   71 51 160 90 ""  "" "Listbox Example"
10  10 85  40 9000   1352728579"listbox" ""  0
6   60 40  14 1   1342373889"button"  "OK"   0
54  60 40  14 2   1342373888"button"  "Cancel"  0
99  60 40  14 21  1342373888"button"  "Info..." 0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption




ΓòÉΓòÉΓòÉ 84. DlgHideControl ΓòÉΓòÉΓòÉ

This function hides or shows the specified control in list boxes, combo boxes,
and edit boxes that have been created using the Dialog Editor.


Syntax
DlgHideControl(Hdlg, ID, Hide)
Hdlg identifies the dialog box handle.
ID is the number the Dialog Editor automatically assigns to a control. An edit
box can have an ID value from 8000 through 8999. A list box can have an ID
value from 9000 through 9499. A combo box can have an ID value from 9500
through 9999.
Hide is either equal to 1 if you want to hide the control, or 0 if you want to
display the control.

Return Value

Example
Function Main()
Mac = GetRunningMacroFile$()
SetDlgCallBack(21, "{Mac}!Hide")
SetDlgCallBack(8000, "{Mac}!InEdit")
Box = DialogBox(".","Demo2")
End Function


Function InEdit(Hdlg, id, value)
IgnoreKeyBoard(2)    ' don't allow the keyboard to cancel the macro
Text = GetDlgITemText(Hdlg, 8000)
DlgSetCaption(Hdlg, text)
End Function

Function Hide(Hdlg, id, value)
DlgHideControl(Hdlg, 8000, 1)  ' hide the editboxk
End Function


DIALOG Demo2
-2134376448   4   95 57 123 58 ""  "" "Editbox Example"
6   36 40  14 1   1342373889"button"  "OK"   0
52  36 44  14 21  1342373888"button"  "Hide editbox"   0
6   17 89  12 8000   1350631552"edit" "" 0
5   5  77  10 1000   1342177280"static"  "Enter some text:"   0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption



ΓòÉΓòÉΓòÉ 85. DlgKeyInterrupt ΓòÉΓòÉΓòÉ

This function sets a callback function that is "called" when the user presses
the specified key while processing a macro dialog box. It should be used before
the DialogBox statement and is in effect during that dialog box only. This
function is passed the dialog box handle (HDLG) and the virtual key.


Syntax
DlgKeyInterrupt(Key, Function)
Key is a virtual key, such as [F1] or [PgDown]. The [F1] key should be set if
you are using the "AmiDialog" in the Dialog code. This allows you to imitate
the help system.
Function is the function that is executed when the specified key is pressed.
This parameter may contain the macro file name or the function within that file
to call.

Return Value
This function does not return a value.

Example
FUNCTION Example()
' run the HelpFun function if user hits F1 or Help button
DlgKeyInterrupt([F1], "HelpFun")
DialogBox(".", "QT") 'read dialog box from this file
END FUNCTION

FUNCTION HelpFun(hdlg, key)
Message("This is help!")
END FUNCTION

DIALOG QT
-2134376448 4 58 44 160 50 "" "AmiDialog" "Key Int Text"
FONT 8 "Helv"
112 6 40 14 1 1342373889 "button" "OK" 0
112 24 40 14 2 1342373888 "button" "Cancel" 0
14 8 50 12 20 1342242825 "button" "Radio 1" 0
14 22 50 12 21 1342242825 "button" "Radio 2" 0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgLimitText
    DlgSetCaption
    KeyInterrupt
    MouseInterrupt


ΓòÉΓòÉΓòÉ 86. DlgLimitText ΓòÉΓòÉΓòÉ

This functions limits the length of the text string a user can enter in an edit
box that has been created using the Dialog Editor.


Syntax
DlgLimitText(Hdlg, ID, Length)
Hdlg identifies the dialog box handle.
ID is the number the Dialog Editor automatically assigns to a control. An edit
box can have an ID value from 8000 through 8999.
Length is the number of characters the user is allowed to enter in the text
string.

Return Value

Example
Function Main()
Mac = GetRunningMacroFile$()
SetDlgCallBack(0, "{Mac}!InitDlg")
Box = DialogBox(".","Demo2")
If Box <>1
    Exit Function
Endif
Text = GetDialogField$(8000)
Message("User entered {Text}")
End Function

Function InitDlg(Hdlg)
' impose a text limit on the editbox
' this is executed before the dialog is displayed
DlgLimitText(Hdlg, 8000, 12)
End Function

DIALOG Demo2
-2134376448   4   95 57 123 58 ""  "" "Editbox Example"
6   36 40  14 1   1342373889"button"  "OK"   0
52  36 40  14 2   1342373888"button"  "Cancel"  0
6   17 89  12 8000   1350631552"edit" "" 0
5   5  77  10 1000   1342177280"static"  "Enter some text:"   0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgSetCaption


ΓòÉΓòÉΓòÉ 87. DlgSetCaption ΓòÉΓòÉΓòÉ

This functions inserts a title string in a dialog box that has been created
using the Dialog Editor.


Syntax
DlgSetCaption(Hdlg, Caption String)
Hdlg identifies the dialog box handle.
Caption String is the title string to display in the dialog box.

Return Value

Example
Function Main()
Mac = GetRunningMacroFile$()
SetDlgCallBack(21, "{Mac}!Hide")
SetDlgCallBack(8000, "{Mac}!InEdit")
Box = DialogBox(".","Demo2")
End Function


Function InEdit(Hdlg, id, value)
IgnoreKeyBoard(2)    ' don't allow the keyboard to cancel the macro
Text = GetDlgITemText(Hdlg, 8000)
DlgSetCaption(Hdlg, text)
End Function

Function Hide(Hdlg, id, value)
DlgHideControl(Hdlg, 8000, 1)  ' hide the editboxk
End Function


DIALOG Demo2
-2134376448   4   95 57 123 58 ""  "" "Editbox Example"
6   36 40  14 1   1342373889"button"  "OK"   0
52  36 44  14 21  1342373888"button"  "Hide editbox"   0
6   17 89  12 8000   1350631552"edit" "" 0
5   5  77  10 1000   1342177280"static"  "Enter some text:"   0
END DIALOG

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText



ΓòÉΓòÉΓòÉ 88. DLLCall ΓòÉΓòÉΓòÉ

This function verifies that a Dynamic Link Library (DLL) function is available
and loads it into memory. DLL functions are extremely powerful tools that
provide access to OS/2 functions located in PMWIN.DLL, PMGPI.DLL, DOSCALL1.DLL,
and PMPRF.DLL, and to user written functions. DLL functions are for the benefit
of experienced programmers.


Before using DLL functions, make sure that you know how to use them correctly.
If DLL functions are used incorrectly, you may have problems with Ami Pro and
OS/2 after their use.

The parameter list, if described, must be a string containing letters
specifying the variable type of the function's return value. This must be
followed by one letter per parameter.

Syntax
DLLCall(Module, Function, Parameters)
Module is the full path name and file name of the DLL. You must have .dll as
the file name extension.
Function is the ordinal number representing the DLL function to call. You
should not use the name of the DLL function because Ami Pro assumes the 16 bit
OS/2 1.3 function. The ordinal numbers for PMWIN.DLL, PMGPI.DLL, DOSCALL1.DLL,
and PMPRF.DLL are located in the IBM OS/2 Programmer's Toolkit in the bseord.h
file.
Parameters are the types for the parameters of the function. The first
parameter type is the type for the return value. All other parameters are in
order for the types of parameters that pass to the function.
    A - Boolean integer
    B - Far pointer to double
    C - Far pointer to string
    E - Double
    H - Unsigned integer
    I - Integer
    J - Unsigned long integer
    L - Far pointer to word (Word Far *)
    M - Far pointer to array or string (CHAR FAR * FAR *)
    N - Far pointer to array or words (Word Far *)
    O - Far pointer to a long (LONG FAR *)
NOTE: You must not use spaces between the commas.

Return Value
The return value of the DLLCall function defined by the module that is called.

Example
FUNCTION testdll()
                     'call the function WinQueryActiveWindow
define GetActive()   DLLCall("e:\os2\dll\pmwin.dll,799,JJ",%1)
active=GetActive(1)
message("The active window handle is {active}")
end function

See also:

    DLLFreeLib
    DLLLoadLib
    Exec


ΓòÉΓòÉΓòÉ 89. DLLFreeLib ΓòÉΓòÉΓòÉ

This function unloads the library loaded by the DLLLoadLib function.


Syntax
DLLFreeLib(LibID)
LibID is the ID returned by the DLLLoadLib function.

Return Value
1  (TRUE) if the DLL was successfully freed.
0  (FALSE) if the DLL could not be freed.

Example
FUNCTION Example()
Text = Query$("Enter text for window:")  'Get new title bar text
hGetActiveWindow = DLLLoadLib("User", "GetActiveWindow", "H")
' Load DLL into memory
hWnd = DLLCall(hGetActiveWindow)   'Call for active window handle
hSetActiveText = DLLLoadLib("User", "SetWindowText", "IHC")
' Load DLL into memory
DLLCall(hSetActiveText, hWnd, Text)   'Call to set title bar text
DLLFreeLib(hGetActiveWindow)   'Free DLL
DLLFreeLib(hSetActiveText)     'Free DLL
END FUNCTION

See also:

    DLLCall
    DLLLoadLib


ΓòÉΓòÉΓòÉ 90. DLLLoadLib ΓòÉΓòÉΓòÉ

This function is used to verify that a Dynamic Link Library (DLL) function is
available. It is also used to load DLL functions into memory so that they can
be used later. Any DLL function can be used in your macro. The parameter list,
if described, must be a string containing letters specifying the variable type
of the function's return value. This must be followed by one letter per
parameter. DLL functions located in PMWIN, PMGPI, PMPRF, and DOSCALL1 must be
loaded.


DLL functions are extremely powerful tools that provide access to OS/2
functions and to specially written functions. They are for the benefit of
experienced programmers.

Before using these functions, make sure that you know how to use them
correctly. If they are used incorrectly, you may have problems with Ami Pro and
OS/2 after their use.

Syntax
DLLLoadLib(Module, Function, Parameters)
Module  is the full path name and file name of the DLL. You must have .dll as
the file name extension.
Function is the name of the function within the DLL module to be accessed.
Parameters is a string with the prototype parameters and return code for the
function.
These parameters are passed to the function when it is called. The letter codes
for variable types are:
    A - Boolean integer
    B - Far pointer to double
    C - Far pointer to string
    E - Double
    H - Unsigned integer
    I - Integer
    J - Unsigned long integer
    L - Far pointer to word (Word Far *)
    M - Far pointer to array or string (CHAR FAR * FAR *)
    N - Far pointer to array or words (Word Far *)
    O - Far pointer to a long (LONG FAR *)

Return Value
1  (TRUE) if the DLL was successfully loaded.
0  (FALSE) if the DLL could not be loaded or could not be found.

Example
FUNCTION Example()
Text = Query$("Enter text for window:")  'Get new title bar text
hGetActiveWindow = DLLLoadLib("User", "GetActiveWindow", "H")
' Load DLL into memory
hWnd = DLLCall(hGetActiveWindow)   'Call for active window handle
hSetActiveText = DLLLoadLib("User", "SetWindowText", "IHC")
' Load DLL into memory
DLLCall(hSetActiveText, hWnd, Text)   'Call to set title bar text
DLLFreeLib(hGetActiveWindow)   'Free DLL
DLLFreeLib(hSetActiveText)     'Free DLL
END FUNCTION

See also:

    DLLCall
    DLLFreeLib


ΓòÉΓòÉΓòÉ 91. DocInfo ΓòÉΓòÉΓòÉ

This function enters new values in the current document's Document Info. This
function is equivalent to choosing File Doc Info. The DocInfo function does not
allow the user to examine the system fields in the document information, nor
does it allow the macro to determine their values.


Syntax
DocInfo(Description, Keyword, Flag)
Description is the text that replaces the contents of the Description field in
the document description.
Keyword is the text that replaces the contents of the Keyword field in the
document description.
Flag indicates whether or not a document is locked. It also indicates whether a
frame macro should be executed when the user clicks on a frame. It is one of
the following values:
    DocResetFlag (0) - Do not lock the document and do not run frame macros
    DocRunMacro (1) - Run frame macros
    DocLock (2) - Lock for annotations (not available in OS/2)
    DocRevLock (4) - Lock revision marking on
Lock does not take effect until the document is saved. The notes functions
available are editing, inserting, and deleting.

To display the Document Info dialog box and allow the user to examine and fill
out the document description: DocInfo

Return Value
1  (TRUE) if the new document info fields were saved.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
descrip = "This is my doc description"
keywords = "macro, docinfo"
flag = DocRunMacro + DocLock
DocInfo(descrip, keywords, flag)
END FUNCTION

See also:

    DocInfoFields
    GetDocInfo$
    InsertDocInfoField
    InsertDocInfo
    RenameDocInfoField



ΓòÉΓòÉΓòÉ 92. DocInfoFields ΓòÉΓòÉΓòÉ

This function replaces the contents of the text in a user field. The user
fields are located in the document information. This function is equivalent to
choosing File Doc Info and choosing Fields.


Syntax
DocInfoFields(Field1, Field2, Field3, Field4, Field5, Field6, Field7, Field8)
field1  is the text that replaces the contents of user field 1.
field2  is the text that replaces the contents of user field 2.
field3  is the text that replaces the contents of user field 3.
field4  is the text that replaces the contents of user field 4.
field5  is the text that replaces the contents of user field 5.
field6  is the text that replaces the contents of user field 6.
field7  is the text that replaces the contents of user field 7.
field8  is the text that replaces the contents of user field 8.

Return Value
1  (TRUE) if the info fields were successfully changed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the info fields were not changed.

Example
FUNCTION Example()
Dim Field(8)
For t = 1 to 8
    Field(t) = Query$("Enter information for field({t})")
Next
DocInfoFields(Field(1), Field(2), Field(3), Field(4), Field(5), Field(6),
Field(7), Field(8))
END FUNCTION

See also:

    DocInfo
    GetDocInfo$
    InsertDocInfoField
    InsertDocInfo
    RenameDocInfoField



ΓòÉΓòÉΓòÉ 93. DOSchdir ΓòÉΓòÉΓòÉ

This function makes the parameter the current DOS directory. This function does
not change the drive.


Syntax
DOSchdir(Dir)
Dir is the path you wish to make the current directory.

Return Value
0  if the directory was successfully changed.
-1  if the directory could not be changed or does not exist.

Example
FUNCTION Example()
Dir = Query$("What directory do you want to change to?")
IF -1 = DOSchdir(Dir)
    Message("Could not change to {Dir}")
ENDIF
NewDir = GetCurrentDir$()
Message("The current directory reported by DOS is: {NewDir}")
END FUNCTION

See also:

    DOSCopyFile
    DOSDelFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSmkdir
    DOSRename
    DOSrmdir
    DOSSetFileAttr
    FileManagement


ΓòÉΓòÉΓòÉ 94. DOSCopyFile ΓòÉΓòÉΓòÉ

This function copies an existing file.


Syntax
DOSCopyFile(OldFile, NewFile)
OldFile is the name of the file to be copied. Use the path if the file to be
copied is not in the current directory.
NewFile is the name to which the file is being copied. Use the path if you do
not want the file copied to the current working directory.

Return Value
1  (TRUE) if the file was successfully copied.
0  (FALSE) if the file was not copied.

Example
FUNCTION Example()
OpenFile = GetOpenFileName$() ' get the open file name including path
Backupfile = "C:\curfile.bak"
DOSCopyFile(OpenFile, Backupfile) ' make a backup copy of the open file
DOSDelFile(Backupfile) ' delete the back up file
END FUNCTION

See also:

    DOSchdir
    DOSDelFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSmkdir
    DOSRename
    DOSrmdir
    DOSSetFileAttr
    FileManagement


ΓòÉΓòÉΓòÉ 95. DOSDelFile ΓòÉΓòÉΓòÉ

This function deletes an existing file.


Syntax
DOSDelFile(FileName)
FileName is the name of the file to be deleted. If the file is not in the
current directory, the path must be used.

Return Value
0  if the file was deleted.
-1 (NotFound) if the file was not deleted.

Example
FUNCTION Example()
OpenFile = GetOpenFileName$() ' get the open file name including path
Backupfile = "C:\curfile.bak"
DOSCopyFile(OpenFile, Backupfile) ' make a backup copy of the open file
DOSDelFile(Backupfile) ' delete the back up file
END FUNCTION

See also:

    DOSchdir
    DOSCopyFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSmkdir
    DOSRename
    DOSrmdir
    DOSSetFileAttr
    FileManagement




ΓòÉΓòÉΓòÉ 96. DOSGetEnv ΓòÉΓòÉΓòÉ

This function searches the DOS environment for the passed variable.


Syntax
DOSGetEnv$(Var)
Var is the name of the environment variable to search for.

Return Value
The information stored in the environment variable if the variable is found.
The null string ("") if the variable is not found.

Example
FUNCTION Example()
Var = "Path"
Path = DosGetEnv$(Var)
Message(Path)
END FUNCTION

See also:

    DOSchdir
    DOSCopyFile
    DOSDelFile
    DOSGetFileAttr
    DOSmkdir
    DOSRename
    DOSrmdir
    DOSSetFileAttr
    FileManagement


ΓòÉΓòÉΓòÉ 97. DOSGetFileAttr ΓòÉΓòÉΓòÉ

This function returns the attributes for a specified file.


Syntax
DOSGetFileAttr(FileName)
FileName is the name of the file for which the attributes are determined. If
the file is not in the current directory, the path must be used.

Return Value
A bit number corresponding to the attributes for the specified file. The bit
values that a file can have are:
    1 - Read-only
    2 - Hidden
    4 - System
    8 - Volume ID
    16 - Subdirectory
    32 - Archive
These bit numbers are added together if more than one attribute is set for that
file. Use the binary operator OR (|) or AND (&) to extract them.
-1  if the attributes could not be found

Example
FUNCTION Main()
Filledit(9001,"*.*")
Box = DialogBox(".","GetAttrib")
IF Box<>1
    EXIT FUNCTION
ENDIF
Dir = GetCurrentDir$()
Name = GetdialogField$(9001)
FileName = StrCat$(Dir,Name)
Attrib = DosGetFileAttr(Name)
Message("{Name} is set as {Attrib}")
END FUNCTION

DIALOG GetAttrib
-2134376448 4 90 34 110 85 "" "" "Get File Attributes"
FONT 8 "HELV"
4 14 52 64 9001 1352728579 "listbox" "" 0
5 3 53 10 7999 1342177280 "static" "" 0
65 5 40 14 1 1342373889 "button" "OK" 0
65 22 40 14 2 1342373888 "button" "Cancel" 0
END DIALOG


See also:

    DOSchdir
    DOSCopyFile
    DOSDelFile
    DOSGetEnv$
    DOSmkdir
    DOSRename
    DOSrmdir
    DOSSetFileAttr
    FileManagement


ΓòÉΓòÉΓòÉ 98. DOSmkdir ΓòÉΓòÉΓòÉ

This function creates a directory.


Syntax
DOSmkdir(Dir)
Dir is the name of the directory to be created.

Return Value
0  if the directory was created.
-1  if the directory could not be created.

Example
FUNCTION Example()
Dir = Query$("What is the name of the new directory?")
IF -1 = DOSmkdir(Dir)
    Message("Could not create directory {Dir}")
ELSE
    Message("Directory {Dir} created.")
ENDIF
END FUNCTION

See also:

    DOSchdir
    DOSCopyFile
    DOSDelFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSRename
    DOSrmdir
    DOSSetFileAttr
    FileManagement


ΓòÉΓòÉΓòÉ 99. DOSRename ΓòÉΓòÉΓòÉ

This function renames an existing file.


Syntax
DOSRename(OldName, NewName)
OldName is the name of the file to be renamed. If the file is not in the
current directory, the path must be used.
NewName is the name to which the file is being renamed. If you do not want this
file to be placed in the current directory, the path must be used.
The NewName file name must not exist in the specified directory.

Return Value
0  if the file was renamed.
Non zero number if the file could not be renamed or if the specified new file
name exists.

Example
FUNCTION Example()
Filename = Query$("What file (with path) do you want to perform an action on?")
IF Decide("Do you want to Copy {Filename}?")
    Filename2 = Query$("What file do you want to copy {Filename} to?")
    IF 0 = DOSCopyFile(Filename, Filename2)
       Message("Could not copy {Filename} to {Filename2}")
    ENDIF
ELSEIF Decide("Do you want to Rename {Filename}?")
    Filename2 = Query$("What is the new name for {Filename}?")
    IF 0 != DOSRename(Filename, Filename2)
       Message("Could not rename {Filename} as {Filename2}")
    ENDIF
ELSEIF Decide("Do you want to Delete {Filename}?")
    IF Decide("Are you SURE you want to Delete {Filename}?")
       IF -1 = DOSDelFile(Filename)
       Message("Could not delete {Filename}")
       ENDIF
    ENDIF
ENDIF
END FUNCTION

See also:

    DOSchdir
    DOSCopyFile
    DOSDelFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSmkdir
    DOSrmdir
    DOSSetFileAttr
    FileManagement


ΓòÉΓòÉΓòÉ 100. DOSrmdir ΓòÉΓòÉΓòÉ

This function removes an existing directory.


Syntax
DOSrmdir(Dir)
Dir is the name of the existing directory to be removed.
The directory must be empty and cannot be the current working directory or the
root directory.

Return Value
0  if the directory was successfully removed.
-1  if the directory could not be removed.

Example
FUNCTION Example()
Dir = Query$("What is the name of the directory you want to delete?")
IF Decide("Are you SURE you want to delete {Dir}?")
    IF -1 = DOSrmdir(Dir)
       Message("Could not remove {Dir}. The directory may not be empty.")
    ELSE
       Message("The directory {Dir} has been removed.")
    ENDIF
ENDIF
END FUNCTION

See also:

    DOSchdir
    DOSCopyFile
    DOSDelFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSmkdir
    DOSRename
    DOSSetFileAttr
    FileManagement


ΓòÉΓòÉΓòÉ 101. DOSSetFileAttr ΓòÉΓòÉΓòÉ

This function sets the attribute bits for an existing file.


Syntax
DOSSetFileAttr(FileName, Attr)
FileName is the name of the file for which the attribute bits are to be set. If
the file is not in the current directory, the path must be used.
Attr is the number of the attribute to be set. The bit values that a file can
have are:
    1 - Read-only
    2 - Hidden
    4 - System
    8 - Volume ID
    16 - Subdirectory
    32 - Archive
To set more than one attribute, add the bit values for the attributes you want
to set and use that number.

Return Value
0  if the attributes were successfully set.

Example
FUNCTION Example()
Filledit(9001,"*.*")
Box = DialogBox(".","GetAttrib")
IF Box<>1
    Exit Function
ENDIF
Dir = GetCurrentDir$()
Name = GetdialogField$(9001)
FileName = StrCat$(Dir,Name)
IF 0 = DosSetFileAttr(Name,1)
    Message("{Name} is set as Read-Only")
ENDIF
END FUNCTION

DIALOG GetAttrib
-2134376448 4 90 34 110 85 "" "" "Get File Attributes"
FONT 8 "HELV"
4 14 52 64 9001 1352728579 "listbox" "" 0
5 3 53 10 7999 1342177280 "static" "" 0
65 5 40 14 1 1342373889 "button" "OK" 0
65 22 40 14 2 1342373888 "button" "Cancel" 0
END DIALOG

See also:

    DOSchdir
    DOSCopyFile
    DOSDelFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSmkdir
    DOSRename
    DOSrmdir
    FileManagement


ΓòÉΓòÉΓòÉ 102. DraftMode ΓòÉΓòÉΓòÉ

This function changes the current document in Ami Pro from Layout Mode or
Outline Mode to Draft Mode. This function is equivalent to choosing View Draft
Mode.


Syntax
DraftMode()

Return Value
1  (TRUE) if the  view  mode was changed.
0  (NoAction) if no action was taken because the document was already in Draft
Mode.

Example
FUNCTION Example()
DraftMode()
Mode = GetMode()
Message("Mode = {Mode}")
END FUNCTION

See also:

    EnlargedView
    FacingView
    FullPageView
    GetMode
    GetViewLevel
    LayoutMode
    OutlineMode
    StandardView


ΓòÉΓòÉΓòÉ 103. EditFormula ΓòÉΓòÉΓòÉ

This function displays the  edit formula dialog box. This function is
equivalent to choosing Table Edit Formula. This function does not automatically
allow a macro to insert a formula into a cell. To insert a formula
automatically, use the SetFormula function.


Syntax
EditFormula()

Return Value
1  (TRUE) if the dialog box is displayed.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
OnKey([CtrlAlte], EditFormula, 0)
Message("Press Ctrl+Alt+E to edit the formula in a table cell")
END FUNCTION

See also:

    SetFormula


ΓòÉΓòÉΓòÉ 104. ElevatorLeftRight ΓòÉΓòÉΓòÉ

This function scrolls the document to a new position in the file without moving
the insertion point. This function is equivalent to dragging the slider box on
the horizontal scroll bar left or right.


This function may be used only through macro keystroke record.

The parameter for this function is generated by OS/2 and can not be selected
from a list of values.

Syntax
ElevatorLeftRight()

Return Value
This function does not return a value.

Example
FUNCTION Example()
ElevatorLeftRight
END FUNCTION

See also:

    CharLeft
    CharRight
    ElevatorUpDown
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 105. ElevatorUpDown ΓòÉΓòÉΓòÉ

This function scrolls the document to a new position in the file without moving
the insertion point. This function is equivalent to dragging the slider box on
the vertical scroll bar up or down.


This function may be used only through macro keystroke record.

The parameter for this function is generated by OS/2 and can not be selected
from a list of values.

Syntax
ElevatorUpDown()

Return Value
1  (TRUE) if the document was able to scroll.
-2  (GeneralFailure) if the document could not be scrolled.

Example
FUNCTION Example()
ElevatorUpDown
END FUNCTION

See also:

    CharLeft
    CharRight
    ElevatorLeftRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 106. EndOfFile ΓòÉΓòÉΓòÉ

This function scrolls the document to the end of the file without moving the
insertion point. This function is equivalent to dragging the slider box on the
vertical scroll bar to the extreme bottom.


Syntax
EndOfFile()

Return Value
1  (TRUE) if the document was able to scroll.
-2  (GeneralFailure) if the document could not be scrolled.

Example
FUNCTION Example()
Action = Query$("Move to (T)op of file, or (E)nd of file?")
Action = UCASE$(Left$(Action, 1))
SWITCH Action
CASE "T"
message(TopOfFile())
CASE "E"
message(EndOfFile())
default
Message("""T"" or ""E"" will do just fine, please.")
ENDSWITCH
END FUNCTION

See also:

    CharLeft
    CharRight
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 107. EnlargedView ΓòÉΓòÉΓòÉ

This function changes the current view level to  enlarged view. This function
is equivalent to choosing View Enlarged View.


Syntax
EnlargedView()

Return Value
This function returns 1.

Example
FUNCTION Example()
Message("Now switching to Enlarged View")
EnlargedView()
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    CustomView
    FacingView
    FullPageView
    GetViewLevel
    LayoutMode
    StandardView



ΓòÉΓòÉΓòÉ 108. Equations ΓòÉΓòÉΓòÉ

This function changes to equation mode. This function is equivalent to choosing
Tools Equations. If a frame is selected, it is used. If no frame is selected,
one is created.


This function does not automatically enter equations.

A macro must be edited to insert this non-recordable function.

Syntax
Equations()

Return Value
1  (TRUE) if the equations mode was initiated.
-2  (GeneralFailure) if the mode could not be initiated.

Example
FUNCTION Example()
OnKey([Ctrlshifte], Equations, 0)
Message("Press Ctrl+Shift+E to activate the equation editor.")
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    OnKey


ΓòÉΓòÉΓòÉ 109. EvalField ΓòÉΓòÉΓòÉ

This function passes a power field to the field manager for evaluation and then
returns the result.


Syntax
EvalField(Field)
Field is the power field you wish to evaluate.

Return Value
The result of the specified power field.

Example
FUNCTION Example()
NumberOfPages = EvalField("NumPages")
IF NumberOfPages > 1 'make plural
    Adv = "are"
    s = "s"
ELSE              'make singular
    Adv = "is"
    s = ""
ENDIF
Message("There {Adv} {NumberOfPages} page{s} in this document.")
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate


ΓòÉΓòÉΓòÉ 110. Exec ΓòÉΓòÉΓòÉ

This function executes a program. This function uses OS/2 to start the new
program. This function is equivalent to typing the application's name at an
OS/2 command prompt.


Syntax
Exec(App, Parameters[, State])
App is the name of the program, including extension, which should be executed.
If the desired program has any parameters, they should be passed in Parameters.
If the file to be executed is not in the path, you must supply the path. If the
program has no parameters, a null string("") must be used.
State is a number corresponding to the state that the window (if it is a OS/2
application) should be displayed. This parameter can be one of the following:
    1 - Exec and show the window normally
    2 - Exec the program minimized
    3 - Exec the program maximized

Return Value
A positive number greater than 32 if the program was executed successfully.
If the program fails to execute, OS/2 returns one of the following error codes:
    0 - An application parameter was invalid
    1 - OS/2 could not recognize this type of program - check your App name
    2 - OS/2 error, OS/2 could not exec program
    3 - other OS/2 error
    4 - OS/2 error occured making a DOS call

Example
FUNCTION Example()
if appisrunning("E.EXE")
    ActivateApp("E.EXE")
else
    Exec("E.EXE", "", 1)
endif
END FUNCTION

See also:

    ActivateApp
    Appclose
    AppGetAppCount
    AppGetAppNames
    AppGetWindowPos
    AppHide
    AppIsRunning
    AppMaximize
    AppMinimize
    AppMove
    AppRestore
    AppSendMessage
    AppSize
    DDEExecute
    DDEInitiate
    GetMacPath$





ΓòÉΓòÉΓòÉ 111. FacingView ΓòÉΓòÉΓòÉ

This function changes the current view level to  facing pages View. This
function is equivalent to choosing View Facing Pages. You can use the GetMode
function to determine the current view mode.


You must be in Layout Mode to call this funtion.

Syntax
FacingView()

Return Value
This function returns 1.

Example
FUNCTION Example()
Mode = GetMode()
IF Mode != 1
    ' change to layout mode if not there
    LayoutMode()
ENDIF
FacingView()
END FUNCTION

See also:

    CustomView
    EnlargedView
    FullPageView
    GetMode
    GetViewLevel
    LayoutMode
    StandardView




ΓòÉΓòÉΓòÉ 112. FastFormat ΓòÉΓòÉΓòÉ

This function extracts text formatting information from selected text and then
applies that formatting to other main document text, table text, or text in a
frame. Text formatting is any typeface, point size, color, attribute (bold,
italic, underline, word underline), capitalization, or special effects. This
function enables Fast Format if it is not enabled or disables it if it is
enabled. This function is equivalent to choosing Text Fast Format.


This function can be used to load the text formatting for use with the
ApplyFormat function.

Syntax
FastFormat()

Return Value
This function returns 1.

Example
FUNCTION Example()
FastFormat()   ' Enable Fast Formatting
UserControl("Press Resume to cancel Fast Formatting")
FastFormat()   ' Disable Fast Formatting
END FUNCTION

See also:

    ApplyFormat


ΓòÉΓòÉΓòÉ 113. fclose ΓòÉΓòÉΓòÉ

This function closes an ASCII file that has been opened by the fopen function.
All open files must be closed by the macro that created them, otherwise
unpredictable results occur.


When using ASCII file functions, be careful to ensure that the file was opened
correctly before performing additional ASCII file functions. If the fopen
function was unable to open the desired file, unpredictable results can occur
if the macro attempts to read or write to that file.

Syntax
fclose(Handle)
Handle is the file handle of the file to close.

Return Value
This function does not return a value.

Example
FUNCTION Example()
amidir = GetAmiDirectory$()
' opens for appending; creates this file if it doesn't exist
id = fopen("{amidir}test.txt", "a")
IF id = 0
    exit function
ENDIF
Name=Query$("What is your name?")
fputs(id, Name)
Address= Query$("What is your address?")
fwrite(id, Address)
fwrite(id, "This is right after the address, with no carriage return.")
fclose(id)
Exec("E.EXE", "{amidir}TEST.TXT")
END FUNCTION

See also:

    fgets$
    fopen
    fputs
    fread
    fseek
    ftell
    fwrite



ΓòÉΓòÉΓòÉ 114. fgets ΓòÉΓòÉΓòÉ

This function reads a line of text from the file opened by the fopen function.
The line of text is read from the current file pointer position. When reading a
line of text, the carriage return/line feed combination is stripped from the
end of the line before the line is returned by the function.


When using ASCII file functions, be careful to ensure that the file was opened
correctly before performing additional ASCII file functions. If the fopen
function was unable to open the desired file, unpredictable results can occur
if the macro attempts to read or write to that file.

Syntax
fgets$(Handle)
Handle is the file handle for the file returned by the fopen function.

Return Value
The line of text if the file pointer was not at the end of the file.
-1  if the file pointer was at the end of the file.

Example
FUNCTION Example()
ONERROR toast
ONCANCEL toast
DEFSTR id, Line;
IF 0 != Assign(&id, fopen("c:\AUTOEXEC.BAT", "r"))
    ' create a new file
    New("_BASIC.STY", 0, 0)
    WHILE -1 != Assign(&Line, fgets$(id))
       TYPE("{Line}[Enter]")'type all the text in
    WEND
    toast:
    fclose(id)
ELSE
    Message("Could not open C:\AUTOEXEC.BAT!")
ENDIF
END FUNCTION

See also:

    fclose
    fopen
    fputs
    fread
    fseek
    ftell
    fwrite



ΓòÉΓòÉΓòÉ 115. FieldAdd ΓòÉΓòÉΓòÉ

This function adds a power field. This function is equivalent to choosing Edit
Power Fields Insert.


Syntax
FieldAdd(Field)
Field is the name of the power field to add. To include a quote mark within the
string, use "".

Return Value
The new ID if the power field was successfully added.
-2  (GeneralFailure) if the Power field was not added.

Example
FUNCTION Example()
' add a power field that looks like <TOC 1 "Related Functions">
FieldAdd("TOC 1 ""Related Functions""")
' add a power field that looks like <Index "experience" #>
FieldAdd("Index ""experience"" #")
' add a power field that looks like <CreateDate %DB>
FieldAdd("CreateDate %DB")
END FUNCTION

See also:

    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate


ΓòÉΓòÉΓòÉ 116. FieldAuto ΓòÉΓòÉΓòÉ

This function sets or clears the auto update bit for a power field. This
function is equivalent to choosing Edit Power Fields Insert and choosing Auto
run.


Syntax
FieldAuto(ID, Auto)
ID is the ID for the power field to modify.
Auto is the value of the update bit for the power field and is either a 1 (On)
or a 0 (Off).

Return Value
1  (TRUE) if the bit was set or cleared.
0  (NoAction) if no action was taken.

Example
FUNCTION Example()
FieldCommand()       ' let the user make a power field
both = FieldPrev()
id = MOD(both, 0x10000) 'see FieldNext/FieldPrev for explanation
FieldAuto(id, 1)
END FUNCTION

See also:

    FieldAdd
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate


ΓòÉΓòÉΓòÉ 117. FieldCommand ΓòÉΓòÉΓòÉ

This function displays the Insert Power Fields dialog box. This function is
equivalent to choosing Edit Power Fields Insert.


Syntax
FieldCommand()

Return Value
This function does not return a value.

Example
FUNCTION Example()
FieldCommand()       ' let the user insert a power field
both = FieldPrev()
id = MOD(both, 0x10000) 'see FieldNext/FieldPrev for explanation
FieldAuto(id, 1)
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate


ΓòÉΓòÉΓòÉ 118. FieldEvaluate ΓòÉΓòÉΓòÉ

This function updates the field in the current location of the insertion point.
This function is equivalent to choosing Edit Power Fields Update.


Syntax
FieldEvaluate()

Return Value
1  (TRUE) if the field was updated.
0  (FALSE) if the field was not updated.

Example
FUNCTION Example()
FieldNext()          ' go to the next power field
FieldEvaluate()   ' update it
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate


ΓòÉΓòÉΓòÉ 119. FieldLock ΓòÉΓòÉΓòÉ

This function sets or clears the lock bit for a power field. This function is
equivalent to choosing Edit Power Fields Insert and choosing Lock.


Syntax
FieldLock(ID, Lock)
ID is the ID of the power field to modify.
Lock is the value of the lock bit for the power field and is either a 1 (On) or
a 0 (Off).

Return Value
This function does not return a value.

Example
FUNCTION Example()
FieldCommand()       ' let the user make a power field
both = FieldPrev()
id = MOD(both, 0x10000) 'see FieldNext/FieldPrev for explanation
FieldLock(id, 1)
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate



ΓòÉΓòÉΓòÉ 120. FieldNext FieldPrev ΓòÉΓòÉΓòÉ

These functions go backward to the previous power field or forward to the next
power field. This function is equivalent to choosing Edit Power Fields Next
Field or Edit Power Fields Prev Field.


Syntax
FieldNext()
FieldPrev()

Return Value
0  (NoAction) if no action was taken.
The ID of the next/previous Power Field is a bit number. To extract the ID:
both = FieldNext()   ' or both = FieldPrev()
ID = Mod(both, 0x10000)

Example
FUNCTION Example()
FieldCommand()
both = FieldPrev()   ' or use FieldNext here
id = MOD(both, 0x10000)
FieldAuto(id, 1)
FieldLock(id, 1)
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate


ΓòÉΓòÉΓòÉ 121. FieldRemove ΓòÉΓòÉΓòÉ

This function removes a power field.


Syntax
FieldRemove(ID, 8)
ID identifies the power field. You can obtain the ID of a power field by using
FieldNext or FieldPrev.
8 tells the function to remove the index entry.

Return Value
This function returns 1.

Example
FUNCTION Example()
Both = FieldNext()
id = MOD(Both, 0x10000)     ' see Field Next/Field Prev for explanation
FieldRemove(id, 8)
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldToggleDisplay
    FieldUpdateAll
    FieldUpdate




ΓòÉΓòÉΓòÉ 122. FieldToggleDsplay ΓòÉΓòÉΓòÉ

This function toggles the power field display on or off. This function is
equivalent to choosing View Show Power Fields or View Hide Power Fields.


Syntax
FieldToggleDisplay()

Return Value
This function returns 1.

Example
FUNCTION Example()
UserControl("Click Resume to show power fields.")
FieldToggleDisplay()
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldUpdateAll
    FieldUpdate





ΓòÉΓòÉΓòÉ 123. FieldUpdate ΓòÉΓòÉΓòÉ

This function updates an existing power field. This function is equivalent to
choosing Edit Power Fields Update.


Syntax
FieldUpdate(ID, 0, Field)
ID is the ID of the power field to update.
Field is the name of the power field to update.

Return Value
1  (TRUE) if the Power  field was successfully updated.
-7  (CouldNotFind) if the Power Field could not be located.

Example
FUNCTION Example()
id = FieldAdd("NumPages")      ' add Numpages power field
both = FieldPrev()
id = MOD(both, 0x10000)     ' see Field Next/Field Prev for explanation
FieldUpdate(id, type, "NumPages")     ' updates the Numpages power field
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdateAll



ΓòÉΓòÉΓòÉ 124. FieldUpdateAll ΓòÉΓòÉΓòÉ

This function updates all power fields in the current document. This function
is equivalent to choosing Edit Power Fields Update All.


Syntax
FieldUpdateAll()

Return Value
1  (TRUE) if all of the power fields were successfully updated.

Example
FUNCTION Example()
UserControl("Click Resume to update all power fields.")
FieldUpdateAll()
END FUNCTION

See also:

    FieldAdd
    FieldAuto
    FieldCommand
    FieldEvaluate
    FieldLock
    FieldNext
    FieldPrev
    FieldRemove
    FieldToggleDisplay
    FieldUpdate



ΓòÉΓòÉΓòÉ 125. FileChanged ΓòÉΓòÉΓòÉ

This function reads and optionally sets the file-changed flag internal to Ami
Pro. The file-changed flag determines whether Ami Pro asks the user to save the
document before displaying a new document or exiting the program.


Syntax
FileChanged(Action, NewValue)
Action determines whether to read or set the file changed flag. If the Action
parameter is 1 (TRUE), the state of the flag changes to the second parameter.
If the Action parameter is 0 (FALSE), the parameter is not changed and NewValue
is ignored.
NewValue is the new value used for the file changed flag. This should be set to
a 1 (changed) or a 0 (not changed).

Return Value
A positive number if the file had been changed prior to using the function.
0  (FALSE) if the file had not been changed.
Changing the value of the file changed parameter does not affect the return
value of the function until the subsequent function call.

Example
FUNCTION Example()
TYPE("After typing this text, the file will be marked unchanged and then
closed.")
FileChanged(1, 0)
FileClose()
END FUNCTION

See also:

    FileClose
    FileOpen
    FilePrint
    SaveAs
    Save



ΓòÉΓòÉΓòÉ 126. FileClose ΓòÉΓòÉΓòÉ

This function closes the active document in Ami Pro. This function is
equivalent to choosing File Close.


Syntax
FileClose()

Return Value
1  (TRUE) if the file was successfully closed.
-2  if the file was not closed.

Example
FUNCTION Example()
FileClose()       'Close the current file.
END FUNCTION

See also:

    FileChanged
    FileOpen
    FilePrint
    SaveAs
    Save


ΓòÉΓòÉΓòÉ 127. FileManagement ΓòÉΓòÉΓòÉ

This function opens the Ami Pro File Manager. This function is equivalent to
choosing File File Management. File Management functions cannot be run directly
with this macro function. It opens the Ami Pro File Manager, then immediately
returns control to the macro. The user can do file management functions, close
the window, and return to word processing.


If later functions in the macro involve screen display, these functions cause
the Ami Pro window to obscure the Ami Pro File Management window as the macro
continues to run. Either have the macro pause with a UserControl box or allow
this function to be the last function in the macro.

A macro must be edited to insert this non-recordable function.

Syntax
FileManagement()

Return Value
1  (TRUE) if the File Manager was started.
-2  (GeneralFailure) if the File Manager could not be started.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
OnKey([CtrlAltf], FileManagement, 0)
Message("Press Ctrl+Alt+F to execute the Ami Pro File Manager.")
END FUNCTION

See also:

    DOSchdir
    DOSCopyFile
    DOSDelFile
    DOSGetEnv$
    DOSGetFileAttr
    DOSmkdir
    DOSRename
    DOSrmdir
    DOSSetFileAttr
    OnKey
    UserControl



ΓòÉΓòÉΓòÉ 128. FileOpen ΓòÉΓòÉΓòÉ

This function opens a document in Ami Pro. This function is equivalent to
choosing File Open.


Syntax
FileOpen(FileName, Options, App)
FileName is the name of the document to open. If the file to be opened is not
in the current directory or document directory, the path must be used. To open
the 'Untitled' file, use the null string ("") as the file name.
Options is a bit number corresponding to the options for the file you open. To
use more than one of the options, add them together. Options can be one or more
of the following:
    1 - Ami Pro file
    5 - ASCII file
    8 - Import/Insert
    16 - Non-Ami Pro or Non-ASCII file
    128 - Close current file
App is the file type of the file. The file type must appear as it does in the
amipro3.ini file or the list of file types in the Open dialog box. To open an
Ami Pro file, use the null string ("") here.

To display the Open dialog box and allow the user to choose the file to open:
FileOpen

Return Value
1  (TRUE) if the file was opened.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the file was not opened.
2   if the user created a file that did not exist.

Example
FUNCTION Example()
Filename = Query$("What file do you want to open?")
FileOpen("{Filename}", 1, "")
END FUNCTION

See also:

    ASCIIOptions
    FileChanged
    FilePrint
    GetOpenFileCount
    GetOpenFileName$
    GetOpenFileNames
    New
    SaveAs
    Save





ΓòÉΓòÉΓòÉ 129. FilePrint ΓòÉΓòÉΓòÉ

This function allows printing the current document to a printer. This function
is equivalent to choosing File Print. Before using this function, your macro
should ensure that the document you want to print is active.


Syntax
FilePrint(Copies, StartPage, EndPage, Flag)
Copies is the number of copies of the document to print.
StartPage is the page number to start printing. This parameter is ignored if
the PrintAll option is used, but must still be present.
EndPage is the page number after which to stop printing. This parameter is
ignored if the PrintAll option is used, but must still be present.
Flag is a number that defines the value of other print options, and may be one
or more of the following:
    PrintAll (1) - Prints all pages of document, ignoring StartPage and
    EndPage.
    PrintEven (512) - Prints only the even pages of the document.
    PrintOdd (1024) - Prints only the odd pages of the document.
    PrintBoth (1536) - Prints both even and odd pages of the document.
    4096 - Prints only the current page.
The desired options should be added together to make up the value of the  flag
parameter.

To display the Print dialog box and allow the user to set print options:
FilePrint

Return Value
1  (TRUE) if the print job was successfully completed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the print job failed.

Example
FUNCTION Example()
' print all of the current file with defaults
FilePrint(1, 1, 9999, 1537)
END FUNCTION

See also:

    Merge
    PrintOptions
    PrintSetup


ΓòÉΓòÉΓòÉ 130. FillEdit ΓòÉΓòÉΓòÉ

This function is used to fill the contents of an object that displays in a
dialog box called by the DialogBox function. If the object is an edit box or
static text with an 8000-8999 ID, the text specified in the  value parameter
fills the edit box. If the object is a radio button or check box, the
expression specified in the  value parameter is evaluated and the button is
activated if the result of the evaluation is TRUE. If the result of the
evaluation is FALSE, the button is not activated. If the object is a list box
or a combo box (ID of 9000-9999), the text specified as the  value parameter is
passed. An array can be passed to a list or combo box, filling the list with
the contents of the array. To do so, use indirection (&) and the name of the
array to pass.

You can use this function to put a wildcard pattern into a combo box or a list
box or to append other selection criteria.

Syntax
FillEdit (ID, Value)
ID is the number of the object that receives the value.
Value is either a text string, an expression that evaluates to TRUE or FALSE,
or the address of an existing array. It can be any combination of the following
values:
    1 - Read-only
    2 - Hidden
    4 - System
    16 - Disk volume label
    32 - Directories
    16384 - Drives
    32768 - Files of specified type only

Return Value
This function does not return a value.

Example
FUNCTION Example()
' 32768 + 16384 + 16 = 49168
' this displays only drives and directories
FillEdit(9001, "c:\*.*,49168")
dialogBox(".", "DirsOnly")
END FUNCTION

DIALOG DirsOnly
-2134376448 3 52 48 160 90 "" "" "DirsOnly"
32 20 60 64 9001 1352728579 "listbox" "" 0
112 4 40 14 1 1342373889 "button" "OK" 0
112 22 40 14 2 1342373888 "button" "Cancel" 0
END DIALOG

See also:

    DialogBox
    FillList
    GetDialogField$
    GetDlgItem
    GetDlgItemText
    SetDlgCallback
    SetDlgItemText





ΓòÉΓòÉΓòÉ 131. FindFirst ΓòÉΓòÉΓòÉ

This function finds files that match the FileSpec given to the function. All
files or a subset of files in a directory can be found. The FindFirst$ function
retrieves the first matching file and must be used before the FindNext$
function. FindNext$ finds other files that match the FileSpec.


Syntax
FindFirst$(FileSpec, Attr)
FileSpec describes the file specification desired. It may include a drive
and/or directory name, if desired. The file name portion of the FileSpec can
include the wildcard characters asterisk (*) and question mark (?).
Attr is a number that represents the type of file desired. The possible
attributes are:
    A_Normal (0) - Normal  Files
    A_ReadOnly (1) - Read-only  Files
    A_Hidden (2) - Hidden  Files
    A_System (4) - System  Files
    A_Vollabel (8) -Disk's  Volume Label
    A_Directory (16) - Directories
    A_Archive (32) - Archived files
The values listed above may be added together to retrieve different file types.

Return Value
A string with the matching file.
The null string ("") if no files are matched.

Example
FUNCTION Example()
Filename = Query$("What file do you want to open?")
' check to see if the file exists
IF FindFirst$(Filename, 0)
    FileOpen("{Filename}", 1, "")
ELSE
    Message("Could not find {Filename}.")
ENDIF
END FUNCTION

See also:

    fclose
    fgets$
    FindNext$
    fputs
    fread
    fseek
    ftell
    fwrite



ΓòÉΓòÉΓòÉ 132. FindNext ΓòÉΓòÉΓòÉ

This function finds files that match the FileSpec given to the FindFirst$
function. All files or a subset of files in a directory can be found. The
FindFirst$ function retrieves the first matching file and must be used before
the FindNext$ function. FindNext$ finds other files that match the FileSpec.


Syntax
FindNext$()

Return Value
A string with the matching file.
The null string ("") if no files are matched.

Example
FUNCTION Example()
DIR = Query$("What directory to report on?")
' see if the file exists
File = FindFirst$("{DIR}*.*", 0)
' Type the file names
WHILE File <> ""
    TYPE ("{File}[Enter]")
    File = FindNext$()
WEND
END FUNCTION

See also:

    fclose
    fgets$
    FindFirst$
    FindNext$
    fputs
    fread
    fseek
    ftell
    fwrite




ΓòÉΓòÉΓòÉ 133. FindReplace ΓòÉΓòÉΓòÉ

This function allows the user to view the Find & Replace dialog box. This
function is equivalent to choosing Edit Find & Replace. This function does not
automatically replace words. If automatic Find & Replace is desired, use the
Replace function instead.

A macro must be edited to insert this non-recordable function.

Syntax
FindReplace()

Return Value
1  (TRUE) if the Find & Replace function was started.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
FindReplace()
END FUNCTION

See also:

    GoToCmd
    Replace




ΓòÉΓòÉΓòÉ 134. FontChange ΓòÉΓòÉΓòÉ

This function sets the font, family, color, and size to be used for selected
text. This function is equivalent to choosing Text Font.


Syntax
FontChange(Name, PitchFamily, Color, Size)
Name is the name of the font to use. The name of the font is the font name, as
seen in the Font list box in the menu.
PitchFamily is a combination of the pitch of the font and the typestyle
parameters.
Pitch is one of the following values:
    False (0) - Not  Specified
    FixedPitch (1) - This is a fixed pitch font
    VariablePitch (2) - This is a proportional font
Family is one of the following typeface families:
    False (0) - Not  Specified
    Roman (16) - Roman-like typestyle; proportional pitch, serif
    Swiss (32) - Swiss-like typestyle; proportional pitch, sans serif
    Modern (48) - Modern-like typestyle; fixed pitch, could be either serif or
    sans serif
    Script (64) - Script-like typestyle, such as Brush or Park Avenue
    Decorative (80) - Decorative typeface, such as Old English
One value for Pitch and one value for family should be added together to make
up the PitchFamily parameter. This parameter is used to determine another font
if the font named is not available on the printer.
Color is a numeric representation of the color of the font. It is one of the
following values:
    White (16777215) - White
    Cyan (16776960) - Light  Blue
    Yellow (65535) - Yellow
    Magenta (16711935) - Purple
    Green (65280) - Green
    Red (255) - Red
    Blue (16711680) - Blue
    Black (0) - Black
Size is expressed in twips (1 inch = 1440 twips). An 8 point font is 160 twips.
10 point is 200 twips; 12 point is 240 twips, etc. The formula to determine
twips from point size is pointsize * 20.

To display the dialog box to allow the user to select the desired font:
FontChange

Return Value
1  (TRUE) if the font was changed.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
DEFSTR Name, Color, Size, Family;
' get the current font information
GetCurFontInfo(&Name, &Color, &Size, &Family)
' increase pointsize by two and calculate the twips
Size = ((Size / 20) + 2) * 20
' change font
FontChange(Name, Family, Color, Size)
END FUNCTION

See also:

    FontFaceChange
    FontPointSizeChange
    FontRevert
    ModifyFont
    NormalText
    Spacing





ΓòÉΓòÉΓòÉ 135. FontFaceChange ΓòÉΓòÉΓòÉ

This function changes the selected font for the active document. This function
is equivalent to choosing a font from the status bar. Through the status bar,
the user can only select from the fonts available on the printer. Using this
function, any type of font can be requested. When it is time to display or
print the font, Ami Pro selects the closest matching font to the specification
given.


Syntax
FontFaceChange(Name)
Name is the name of the font to be used. The font name is selected from the
list of names displayed in the FontName section of the status bar.

Return Value
1  (TRUE) if the Font Face was changed.
0  (NoAction) if no action was taken because the font was not available.

Example
FUNCTION Example()
FontName = Query$("Please enter a font name.")
ReturnValue = FontFaceChange(FontName)
IF ReturnValue = 0
    Message("Font ""{FontName}"" not available!")
ENDIF
END FUNCTION

See also:

    FontChange
    FontPointSizeChange
    FontRevert
    ModifyFont
    NormalText


ΓòÉΓòÉΓòÉ 136. FontPointSizeChange ΓòÉΓòÉΓòÉ

This function changes the point size of the selected font for the active
document. This function is equivalent to choosing a point size from the status
bar.


Syntax
FontPointSizeChange(Size)
Size is the point size to use. The point size is selected from the list of
sizes displayed in the pointsize section of the status bar.

Return Value
This function returns 1.

Example
FUNCTION Example()
PointSize = Query$("Please enter a new point size.")
FontPointSizeChange(PointSize)
Message("The new point size is {PointSize}")
END FUNCTION

See also:

    FontChange
    FontFaceChange
    FontRevert
    ModifyFont
    NormalText


ΓòÉΓòÉΓòÉ 137. FontRevert ΓòÉΓòÉΓòÉ

This function changes the text font to the font defined by the current
paragraph style. This function is equivalent to choosing Text Font and
selecting the Revert to s tyle check box.


Syntax
FontRevert()

To display the Font dialog box and allow the user to select the font that
should be used for text: FontChange

Return Value
This function does not return a value.

Example
FUNCTION Example()
WHILE CurShade$() = ""
    UserControl("Select the text to revert back to the style...")
WEND
FontRevert()
END FUNCTION

See also:

    FontChange
    FontFaceChange
    FontPointSizeChange
    ModifyFont
    NormalText


ΓòÉΓòÉΓòÉ 138. Footnotes ΓòÉΓòÉΓòÉ

This function sets the options for footnotes, as well as allowing the user to
edit, insert, or remove footnotes. This function is equivalent to choosing
Tools Footnotes.


Syntax
Footnotes(Function, Options, StartNum, Length, Indent)
Function is the desired footnote function. The  function parameter is one of
the following values:
    InsFootnote (1) - Insert new footnote
    EditFootnote (2) - Edit existing footnote
    SetOptions (3) - Set footnote options only
Options are the desired footnote options. Options are one or more of the
following options:
    Gather (1) - Make the footnotes appear at the end of the document as
    endnotes
    Reset (2) - Reset the footnote numbering on each page
    CustomLength (4) - The footnote separator line is a custom length, rather
    than the length of the margins
Options should be added together if more than one option is desired.
StartNum is the starting footnote number.
Length is the length of the footnote line in twips (1 inch = 1440 twips).
Indent is the indention of the footnote line from the left margin in twips.
If the Custom length option is chosen, the Length parameter should be set to
the length of the line. If the length of the line is not customized, this value
should be set to 0. The Indent parameter should be set to the desired indent
from the left margin. If no indent is desired, the value for Indent should be
0.
To determine the Length and Indent parameters, multiply the desired number of
inches by 1440 to determine the value in twips.

To display the dialog box and allow the user to select the footnote functions
and options: Footnotes

Return Value
1 (TRUE) if the footnote function was completed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the function could not be completed.

Example
FUNCTION Example()
ReturnValue = FootNotes(InsFootnote, Gather, 1, 0, 0)
IF ReturnValue != 1
    SWITCH ReturnValue
    CASE 0
       Message("Footnote function was canceled.")
    CASE -2
       Message("GeneralFailure! Could not insert Footnote.")
    ENDSWITCH
ENDIF
END FUNCTION

See also:

    GoToCmd


ΓòÉΓòÉΓòÉ 139. FormatDate ΓòÉΓòÉΓòÉ

This function takes a date (in seconds) from January 1, 1970, and creates a
formatted string.


Syntax
FormatDate$(Date, Style)
Date is the date to be converted in seconds format.
Style is one of the formats listed below:
    a - 2/18/91
    b - February 18, 1991
    B - FEBRUARY 18, 1991
    c - 18 February 1991
    C - 18 FEBRUARY 1991
    d - Monday, February 18, 1991
    D - MONDAY, FEBRUARY 18, 1991
    e - February 18
    E - FEBRUARY 18
    f - Monday, February 18
    F - MONDAY, FEBRUARY 18
    g - 2/18
    h - 2/18/1991
    i - 18. February
    I - 18. FEBRUARY
    j - 18. February 1991
    k - 1991 February 18
    K - 1991 FEBRUARY 18
    l - February, 1991
    L - FEBRUARY, 1991

Return Value
The date converted to the selected style.

Example
FUNCTION Example()
Born = Query$("What is your Birthday (MM/DD/YYYY)?")
Date = FormatDate$(Now(), "h") 'current date
Time = FormatTime$(Now(), 6)   'current time
Days = DateDiff(Born, Date) ' how many days old
TextDate = FormatDate$(Now(), "d")    'format the date
Message("It is now {Time} on {TextDate}. You are {Days} days old.")
END FUNCTION

See also:

    FormatTime$
    InsertDate
    Now


ΓòÉΓòÉΓòÉ 140. FormatNum ΓòÉΓòÉΓòÉ

This function formats a number to a string, adds an optional prefix at the
beginning, the specified number of digits to the right of the decimal point,
and an optional suffix at the end. The decimal point character and thousands
separator character are taken from the Country Settings option in the System
Setup.


Syntax
FormatNum$(Prefix, Suffix, Decimals, Number)
Prefix is a string that is placed at the beginning of the formatted number.
Suffix is a string that is placed at the end of the formatted number.
Decimals is the number of decimal places to use in the number.
Number is the number to format, without commas, prefix, or suffix.

Return Value
The string with the formatted number.

Example
FUNCTION Example()
Again:
Number = Query$("How much was the sale?")
Where = Query$("Where was the sale made (E)ngland or (A)merica?")
' get the first character and make lowercase
Where = lcase$(Left$(Where, 1))
IF Where = "e"
    Prefix = ""
    Suffix = "╨│"
ELSEIF Where = "a"
    Prefix = "$"
    Suffix = ""
ELSE
    Message("Please choose ""E"" or ""A"".")
    GoTo again
ENDIF
NewNumber = FormatNum$(Prefix, Suffix, 2, Number)
Message("The sale was for {NewNumber}.")
END FUNCTION

See also:

    Instr
    IsNumeric
    LCASE$
    LEN
    MID$
    strcat$
    strchr
    strfield$
    UCASE$


ΓòÉΓòÉΓòÉ 141. FormatSeq ΓòÉΓòÉΓòÉ

This function formats the Number parameter to a specified paragraph style as
defined in the Style parameter.


Syntax
FormatSeq$(Number, Style)
Number is the number you want to format, without commas, prefixes or suffixes.
Style can be one of the paragraph styles listed below:
    1 - 1, 2, 3...
    2 - I, II, III...
    3 - i, ii, iii...
    4 - A, B, C...
    5 - a, b, c...

Return Value
The number in the paragraph style specified.

Example
FUNCTION Example()
Number = Query$("Enter a number to be formatted into the Roman Numeral
equivalent:", "1992")
Number = FormatSeq$(Number, 3)
Message("The Roman Numeral equivalent is ""{Number}"".")
END FUNCTION

See also:

    FormatNum$
    ModifyStyle


ΓòÉΓòÉΓòÉ 142. FormatTime ΓòÉΓòÉΓòÉ

This function takes the time (in seconds) and formats it to a specified style.


Syntax
FormatTime$(Time, Style)
Time is the time to be formatted.
Style is one of the formats listed below:
    1 - 22:28
    2 - 9:00AM
    3 - 09:00AM
    4 - 9:00A
    5 - 09:00A
    6 - 9:00am
    7 - 09:00am
    8 - 9:00a
    9 - 09:00a

Return Value
The time in the format specified.

Example
FUNCTION Example()
Born = Query$("What is your Birthday (MM/DD/YYYY)?")
Date = FormatDate$(Now(), "h") 'current date
Time = FormatTime$(Now(), 6)   'current time
Days = DateDiff(Born, Date) ' how many days old
TextDate = FormatDate$(Now(), "d")    'format the date
Message("It is now {Time} on {TextDate}. You are {Days} days old.")
END FUNCTION

See also:

    FormatDate$
    InsertDate
    Now


ΓòÉΓòÉΓòÉ 143. fputs ΓòÉΓòÉΓòÉ

This function writes a line of ASCII text to the file opened by the fopen
function. The line of text is written at the end of the file. When writing a
line of text, a carriage return/line feed combination is added to the end of
each line before it is written to the file.


When using ASCII file functions, be careful to ensure that the file was opened
correctly before performing additional ASCII file functions. If the fopen
function was unable to open the desired file, unpredictable results can occur
if the macro attempts to read or write to that file.

Syntax
fputs(Handle, Text)
Handle is the file handle for the file returned by the fopen function.
Text is a line of text to be written to the file.

Return Value
This function does not return a value.

Example
FUNCTION Example()
amidir = GetAmiDirectory$()
' opens for appending; creates this file if it doesn't exist
id = fopen("{amidir}test.txt", "a")
IF id = 0
    exit function
ENDIF
Name=Query$("What is your name?")
fputs(id, Name)
Address= Query$("What is your address?")
fwrite(id, Address)
fwrite(id, "This is right after the address, with no carriage return.")
fclose(id)
Exec("E.EXE", "{amidir}TEST.TXT")
END FUNCTION

See also:

    fclose
    fgets$
    fopen
    fread
    fseek
    ftell
    fwrite




ΓòÉΓòÉΓòÉ 144. FrameLayout ΓòÉΓòÉΓòÉ

This function displays the Modify Frame Layout dialog box. This function is
equivalent to choosing Frame Modify Frame Layout. This function does not
automatically modify the  frame layout.


Syntax
FrameLayout()

Return Value
1  (TRUE) if the  frame layout was modified.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the Frame  layout was not modified.

Example
FUNCTION Example()
' create the frame
AddFrame(1440, -1440, 2880, -2880)
IF Decide("Do you want to choose the frame layout options?")
    FrameLayout() 'frame layout dialog box
ELSE
    FrameModInit()      'set up for changes
    Border = (1440 / 5)
    FrameModBorders(1440, 1440, 1440, 1440, Border, Border, Border, Border, 0)
    FrameModLines(20, 3, 1, 0, 16777215, 0, 0, 0, 100, 100)
    FrameModType(Opaque, 0, "")
    FrameModFinish() 'apply changes
ENDIF
END FUNCTION

See also:

    AddFrame
    AddFrameDlg
    BringFrameToFront
    FrameModBorders
    FrameModColumns
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType
    IsFrameSelected
    ModifyLayout
    ModifyStyle
    SendFrameToBack
    SetFrameDefaults



ΓòÉΓòÉΓòÉ 145. FrameModBorders ΓòÉΓòÉΓòÉ

This function allows you to change the size and placement of the selected
frame. This function is equivalent to choosing Frame Modify Frame Layout and
choosing Size & Pos.


You must call the FrameModInit function before using this function. Before the
frame modifications take effect, the FrameModFinish function must be called.

Syntax
FrameModBorders(Width, Height, Top, Left, LeftMargin, TopMargin, RightMargin,
BottomMargin, 0)
Width is the desired width of the frame.
Height is the desired height of the frame.
Top is the distance from the top of the page (vertical starting position).
Left is the distance from the left side of the page (horizontal starting
position).
LeftMargin is the desired left margin of the frame.
TopMargin is the desired top margin of the frame.
RightMargin is the desired right margin of the frame.
BottomMargin is the desired bottom margin of the frame.
The value for all parameters must be given in twips (1 inch = 1440 twips).
Multiply the desired number of inches by 1440 to determine the value in twips.

Return Value
1  (TRUE) if the frame was changed.
-2  (GeneralFailure) if the frame was not changed.

Example
FUNCTION Example()
' create the frame
AddFrame(1440, -1440, 2880, -2880)
IF Decide("Do you want to choose the frame layout options?")
    FrameLayout() 'frame layout dialog box
ELSE
    FrameModInit()      'set up for changes
    Border = (1440 / 5)
    FrameModBorders(1440, 1440, 1440, 1440, Border, Border, Border, Border, 0)
    FrameModLines(20, 3, 1, 0, 16777215, 0, 0, 0, 100, 100)
    FrameModType(Opaque, 0, "")
    FrameModFinish() 'apply changes
ENDIF
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    BringFrameToFront
    FrameLayout
    FrameModColumns
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType
    IsFrameSelected
    SendFrameToBack




ΓòÉΓòÉΓòÉ 146. FrameModColumns ΓòÉΓòÉΓòÉ

This function allows you to change the columns and tabs of the selected frame.
This function is equivalent to choosing Frame Modify Frame Layout and choosing
Cols & Tabs.


You must call the FrameModInit function before using this function. Before the
frame modifications take effect, the FrameModFinish function must be called.

Syntax
FrameModColumns(Options, GutterLine, Color, NumCols[, Cols], NumTabs[, Tabs])
Options is a flag parameter and can have one or more of the following values:
    (0) - No column balance and no line between columns
    (1) - Column balance on
    (2) - Line between columns
GutterLine determines the type of line between the columns. Available lines
styles are:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rules
    DoubleTwoPoint (9) - Parallel two point rules
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
Color is the color of the line between the columns and can be one of the
following:
    White (16777215) - White
    Cyan (16776960) - Light blue
    Yellow (65535) - Yellow
    Magenta (16711935) - Purple
    Green (65280) - Green
    Red (255) - Red
    Blue (16711680) - Blue
    Black (0) - Black
    DarkGray (12566463) - 90% gray scale
    MediumGray (8355711) - 50% gray scale
    LightGray (4144959) - 20% gray scale
    VeryLightGray (1644825) - 10% gray scale
NumCols is the number of columns to use in the frame.
Cols are pairs of numbers that represent the twip offset to the left and right
margin for each column. There should be a pair of offsets for each column.
NumTabs is how many tab pairs follow. The pairs are the type of tabs, followed
by the offset from the left margin.
Tabs are pairs of numbers that represent the type of tab and its offset from
the left margin. The tab type can be one of the following:
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
You can enter one of the following values, using the bitwise operator OR (|):
    0x4000 - for dashed leaders
    0x8000 - for dot leaders
    0xc000 - for underline leaders

Return Value
1  (TRUE) if the lines are modified.
-2  (GeneralFailure) if the lines are not modified.

Example
FUNCTION Example()
AddFrame(1440 -1440 2880 -2880)
FrameModInit()
' no column, no lines between columns, one point rule gutter line
' black line between columns, one column, no tabs
FrameModColumns(0 2 0 1 48 -176 0)
FrameModFinish()
END FUNCTION

See also:

    AddFrame
    AddFrameDlg
    BringFrameToFront
    FrameLayout
    FrameModBorders
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType
    IsFrameSelected
    SendFrameToBack


ΓòÉΓòÉΓòÉ 147. FrameModFinish ΓòÉΓòÉΓòÉ

This function applies all of your changes made when modifying the frame layout.
This function is the last of a series of functions recorded when modifying the
frame layout through Frame Modify Frame Layout. This function is equivalent to
accepting changes entered by choosing Frame Modify Frame Layout.


You must call the FrameModInit function before you call FrameModFinish.

Syntax
FrameModFinish()

Return Value
1  (TRUE) if the frame was changed.
-2  (GeneralFailure) if the frame was not changed.

Example
FUNCTION Example()
' create the frame
AddFrame(1440, -1440, 2880, -2880)
IF Decide("Do you want to choose the frame layout options?")
    FrameLayout() 'frame layout dialog box
ELSE
    FrameModInit()      'set up for changes
    Border = (1440 / 5)
    FrameModBorders(1440, 1440, 1440, 1440, Border, Border, Border, Border, 0)
    FrameModLines(20, 3, 1, 0, 16777215, 0, 0, 0, 100, 100)
    FrameModType(Opaque, 0, "")
    FrameModFinish() 'apply changes
ENDIF
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    BringFrameToFront
    FrameLayout
    FrameModBorders
    FrameModInit
    FrameModLines
    FrameModType
    IsFrameSelected
    SendFrameToBack


ΓòÉΓòÉΓòÉ 148. FrameModInit ΓòÉΓòÉΓòÉ

This function prepares Ami Pro to accept changes to the currently selected
frame when modifying the frame layout. This function is equivalent to
initializing changes made when choosing Frame Modify Frame Layout.


You must have a frame selected before calling this function.

You must call the FrameModFinish function after you call FrameModInit.

Syntax
FrameModInit()

Return Value
1 (TRUE) if the frame was changed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' create the frame
AddFrame(1440, -1440, 2880, -2880)
IF Decide("Do you want to choose the frame layout options?")
    FrameLayout() 'frame layout dialog box
ELSE
    FrameModInit()      'set up for changes
    Border = (1440 / 5)
    FrameModBorders(1440, 1440, 1440, 1440, Border, Border, Border, Border, 0)
    FrameModLines(20, 3, 1, 0, 16777215, 0, 0, 0, 100, 100)
    FrameModType(Opaque, 0, "")
    FrameModFinish() 'apply changes
ENDIF
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    BringFrameToFront
    FrameLayout
    FrameModBorders
    FrameModFinish
    FrameModLines
    FrameModType
    IsFrameSelected
    SendFrameToBack


ΓòÉΓòÉΓòÉ 149. FrameModLines ΓòÉΓòÉΓòÉ

This function applies modifications to the lines around, the background color,
the shadow color, and the shadow placement of the selected frame. This function
is equivalent to choosing Frame Modify Frame Layout and choosing Lines &
shadows.


You must call the FrameModInit function before you use this function. Before
the frame modifications take effect, the FrameModFinish function must be
called.

Syntax
FrameModLines(BorderWhere, PosType, ThickType, ShadeType, BackType,
ShadowColor, ShadowLeft, ShadowTop, ShadowRight, ShadowBottom)
BorderWhere is the lines around a frame. It is one of the following values:
    1 - All
    2 - Left
    4 - Right
    8 - Top
    16 - Bottom
PosType is the position of the border around a frame. It is one of the
following values:
    1 - Middle
    2 - Inside
    3 - Outside
    4 - Close to inside
    5 - Close to outside
You can only choose one value for the PosType parameter.
ThickType is the thickness of the border. It is one of the following values:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rule
    DoubleTwoPoint (9) - Parallel two point rule
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
ShadeType sets the line color. It can be one of the following values:
    Black - 0
    Blue - 16727905
    Cyan - 16776960
    Green - 65280
    Magenta - 16711935
    MedBlue - 16744448
    Orange - 33279
    Pink - 8388863
    Purple - 16711809
    Red - 255
    White - 16777215
    Yellow - 65535
BackType sets the background color. It can be one of the values listed under
ShadeType.
ShadowColor sets the color for the frame shadow. It can be one of the values
listed under ShadeType.
ShadowLeft is the distance that the shadow is offset from the left side of the
frame in twips (1 inch = 1440 twips). It can be one of the following values or
a custom value:
    None (0) - No shadow
    Shallow (57) - Shallow shadow
    Normal (100) - Normal shadow
    Deep (172) - Deep shadow
ShadowTop is the distance that the shadow is offset from the top of the frame
in twips (1 inch = 1440 twips). It can be one of the values listed under
ShadowLeft or a custom value.
ShadowRight is the distance that the shadow is offset from the right side of
the frame in twips (1 inch = 1440 twips). It can be one of the values listed
under ShadowLeft or a custom value.
ShadowBottom is the distance that the shadow is offset from the bottom of the
frame in twips (1 inch = 1440 twips). It can be one of the values listed under
ShadowLeft or a custom value.

Return Value
1  (TRUE) if the lines are modified.
-2  (GeneralFailure) if the lines are not modified.

Example
FUNCTION Example()
' create the frame
AddFrame(1440, -1440, 2880, -2880)
IF Decide("Do you want to choose the frame layout options?")
    FrameLayout() 'frame layout dialog box
ELSE
    FrameModInit()      'set up for changes
    Border = (1440 / 5)
    FrameModBorders(1440, 1440, 1440, 1440, Border, Border, Border, Border, 0)
    FrameModLines(20, 3, 1, 0, 16777215, 0, 0, 0, 100, 100)
    FrameModType(Opaque, 0, "")
    FrameModFinish() 'apply changes
ENDIF
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    FrameLayout
    FrameModBorders
    FrameModFinish
    FrameModInit
    FrameModType
    IsFrameSelected


ΓòÉΓòÉΓòÉ 150. FrameModType ΓòÉΓòÉΓòÉ

This function allows you to set the options for wrapping, placement, and
roundness of the frame. You can also set any macro that is associated with the
selected frame. This function is equivalent to choosing Frame Modify Frame
Layout and choosing Type.


You must call the FrameModInit function before calling this function. Before
the frame modifications take effect, the FrameModFinish function must be
called.

Syntax
FrameModType(Type, Rounded, MacroName)
Type is a setting based on how the text should wrap around a frame, whether a
frame is transparent or opaque, where it is placed on a page, and whether a
macro is assigned to a frame. It is one of the following values:
    TextFrame (512) - Is always used in combination with other values. It is a
    required value.
    Opaque (64) - Hides text or picture behind frame.
    Transparent(0) - Displays text or pictures behind frame.
    Wraparound (128) - Displays text above, below, to the left, or to the right
    of the frame.
    NoWrapBeside (131072) - Displays text above and below frame, but not to the
    left or right of the frame.
    If you do not specify Wraparound or NoWrapBeside, the frame uses the
    default setting of no wrap around.
    AnchorFrame (524288) - Used to anchor frame in its current position or to a
    carriage return. You can not use any repeat values with this value.
    RepeatFrame (256) - Repeats frame on multiple pages. To repeat on all
    pages, do not use in combination with RepeatEven or RepeatOdd.
    RepeatEven (4194304) - Repeats frame on even pages. Use with the
    RepeatFrame value.
    RepeatOdd (8192) - Repeats frame on odd pages. Use with the RepeatFrame
    value.
    Borders (65536) - Uses if frame has borders.
    RunMacro (134217728) - Executes a macro each time the frame is selected.
You can add the values together to get the Type parameter. For example,
FrameModeType(Opaque+TextFrame, 0, ""), or FrameModeType(576, 0, "").
Rounded is the percentage that the corners are rounded (0% = square and 100% =
circle).
MacroName is the name of the macro to run when the frame is selected.

Return Value
1  (TRUE) if the frame was modified.
-2  (GeneralFailure) if the frame was not modified.

Example
FUNCTION Example()
' create the frame
AddFrame(1440, -1440, 2880, -2880)
IF Decide("Do you want to choose the frame layout options?")
    FrameLayout() 'frame layout dialog box
ELSE
    FrameModInit()      'set up for changes
    Border = (1440 / 5)
    FrameModBorders(1440, 1440, 1440, 1440, Border, Border, Border, Border, 0)
    FrameModLines(20, 3, 1, 0, 16777215, 0, 0, 0, 100, 100)
    FrameModType(Opaque, 0, "")
    FrameModFinish() 'apply changes
ENDIF
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    FrameLayout
    FrameModBorders
    FrameModFinish
    FrameModInit
    FrameModLines
    IsFrameSelected


ΓòÉΓòÉΓòÉ 151. fread ΓòÉΓòÉΓòÉ

This function reads a specified number of bytes from the open file. This
function is not line oriented.


When using ASCII file functions, ensure that the file was opened correctly
before performing additional ASCII file functions. If the fopen function was
unable to open the desired file, unpredictable results can occur if the macro
attempts to read or write to that file. If you are reading binary information,
zeroes can confuse this function. You must read binary files one byte at a
time. If the empty string ("") is returned, it indicates a binary zero.

Syntax
fread(Handle, Length)
Handle is the file ID returned by the fopen function.
Len is the number of bytes to read from the file.

Return Value
The data requested from the file.
-1  if the file pointer is at the end of the file.

Example
FUNCTION Example()
DEFSTR string;
id = fopen("test.txt", "w")
IF id != 0
    Name = Query$("What is your name?")
    fwrite(id, Name)
    fwrite(id, BracketsToBin([Enter]))
    fputs(id, Query$("What is your address?"))
    fclose(id)
ENDIF
Exec("NOTEPAD.EXE", "TEST.TXT")
UserControl("Click Resume to continue...")
AppClose("Editor - TEST.TXT")
id2 = fopen("test.txt", "r")
IF id2 != 0
    NameLength = len(Name)
    fseek(id2, 0, 0)
    Name = fread(id2, NameLength)
    EnterKey = BinToBrackets(fread(id2, 2))
    AddressBegins = ftell(id2)
    Address = fgets$(id2)
    Message("Your name is {Name}.")
    Message("Your address is {Address}.")
    Message("EnterKey = {EnterKey}")
    Message("The address begins at the {AddressBegins} byte.")
    fclose(id2)
ENDIF
END FUNCTION

See also:

    BinToBrackets
    BracketsToBin
    fclose
    fopen
    fseek
    ftell
    fwrite


ΓòÉΓòÉΓòÉ 152. FreeGlobalVar ΓòÉΓòÉΓòÉ

This function frees allocated memory assigned to a global variable. Global
variables retain their values until they are freed or you exit Ami Pro, as
opposed to regular variables, which are lost once the function they were
created in is finished.


Syntax
FreeGlobalVar(Name)
Name is the string or number of the existing global variable being freed.

Return Value
1  (TRUE) if the global variable was successfully freed.
0  (FALSE) if no global variable with the requested ID number or name exists.

Example
FUNCTION Example()
AllocGlobalVar("Name", 1)
AllocGlobalVar("Computer", 1)
AllocGlobalVar("Software", 1)
Name = Query$("What is your name?")
Computer= Query$("What kind of computer do you have?")
Software= Query$("What is your favorite piece of software?")
SetGlobalVar("Name", Name)
SetGlobalVar("Computer", Computer)
SetGlobalVar("Software", Software)
CALL Example2()'Call the following function
END FUNCTION

FUNCTION Example2()
NumGlobs=GetGlobalVarCount()
DIM TempArray(Numglobs)
GetGlobalVarNames(&TempArray)
FOR i = 1 to NumGlobs
    VarName=TempArray(i)
    VarContents=GetGlobalVar$(VarName)
    TYPE ("Item {i}, {VarName}, is {VarContents}.[ENTER]")
    FreeGlobalVar(VarName)
NEXT
END FUNCTION

See also:

    AllocGlobalVar
    GetGlobalArray$
    GetGlobalVar$
    SetGlobalArray
    SetGlobalVar
    Using Variables




ΓòÉΓòÉΓòÉ 153. fseek ΓòÉΓòÉΓòÉ

This function moves the file pointer to another location in the file. The file
pointer is the location in the file from which the next text is read.


The fseek function only works reliably when seeking to a location that is zero
bytes from one of the starting locations, or to a location that is a value
returned by the ftell function, starting from the beginning of the file.

When using ASCII file functions, ensure that the file was opened correctly
before performing additional ASCII file functions. If the fopen function was
unable to open the desired file, unpredictable results can occur if the macro
attempts to read or write to that file.

Syntax
fseek(Handle, Location, StartPoint)
Handle is the file handle for the file returned by the fopen function.
Location is the number of characters to move the file pointer. It must be a
positive integer.
StartPoint is the offset in the file to begin moving the file pointer from.
Possible offsets are:
    FBegin (0) - The start of the file
    FCurrent (1) - The current file pointer location
    FEnd (2) - The end of the file

Return Value
This function does not return a value.

Example
FUNCTION Example()
file = Query$("find size of which file?")
id = fopen(file, "r")   'fopen file read-only
fseek(id, 0, 2)   'seek to the end of the file
pos = ftell(id)   'report position of pointer
Message("Size of {file} is {pos} bytes.")
END FUNCTION

See also:

    fclose
    fgets$
    fopen
    fputs
    fread
    ftell
    fwrite





ΓòÉΓòÉΓòÉ 154. ftell ΓòÉΓòÉΓòÉ

This function finds the location of the file pointer in the currently open
file. The file pointer is the location in the file where the next text is read
from or where the previous text was written to.


When using ASCII file functions, be careful to ensure that the file was opened
correctly before performing additional ASCII file functions. If the fopen
function was unable to open the desired file, unpredictable results can occur
if the macro attempts to read or write to that file.

Syntax
ftell(Handle)
Handle is the file handle for the file returned by the fopen function.

Return Value
The current location in the file.

Example
FUNCTION Example()
file = Query$("find size of which file?")
id = fopen(file, "r")   'fopen file read-only
fseek(id, 0, 2)   'seek to the end of the file
pos = ftell(id)   'report position of pointer
Message("Size of {file} is {pos} bytes.")
END FUNCTION

See also:

    fclose
    fgets$
    fopen
    fputs
    fread
    fseek
    fwrite




ΓòÉΓòÉΓòÉ 155. FullPageView ΓòÉΓòÉΓòÉ

This function changes the current view level to Full Page View. This function
is equivalent to choosing View Full Page.


You must be in Layout Mode to call this function.

Syntax
FullPageView()

Return Value
This function returns 1.

Example
FUNCTION Example()
FullPageView()
END FUNCTION

See also:

    CustomView
    EnlargedView
    FacingView
    GetViewLevel
    LayoutMode
    StandardView


ΓòÉΓòÉΓòÉ 156. fwrite ΓòÉΓòÉΓòÉ

This function writes data to the open file. Unlike the fputs function, this one
does not append a carriage return/line feed to the end of the file and is not
line oriented.


When using ASCII file functions, be careful to ensure that the file was opened
correctly before performing additional ASCII file functions. If the fopen
function was unable to open the desired file, unpredictable results can occur
if the macro attempts to read or write to that file.

Syntax
fwrite(Handle, Data[, Length])
Handle is the file ID handle returned by the fopen function.
Data is the string data to place in the file.
Len is the optional length of the string to send. If Len is less than the
actual length of the string data, the data is cut off at the Len position. If
Len is greater than the length of the string data, the remaining positions are
padded with spaces.

Return Value
This function does not return a value.

Example
FUNCTION Example()
amidir = GetAmiDirectory$()
' opens for appending; creates this file if it doesn't exist
id = fopen("{amidir}test.txt", "a")
IF id = 0
    exit function
ENDIF
Name=Query$("What is your name?")
fputs(id, Name)
Address= Query$("What is your address?")
fwrite(id, Address)
fwrite(id, "This is right after the address, with no carriage return.")
fclose(id)
Exec("E.EXE", "{amidir}TEST.TXT")
END FUNCTION

See also:

    BinToBrackets
    BracketsToBin
    fclose
    fopen
    fputs
    fread
    fseek
    ftell
    fwrite


ΓòÉΓòÉΓòÉ 157. Generate ΓòÉΓòÉΓòÉ

This function generates a table of contents and/or an index for the current
document. This function is equivalent to choosing Tools Generate TOC or Tools
Generate Index. You need to specify an output file and Options before you can
generate a TOC using this function. You need to specify an output file and
whether to use Alphabetical separators before you can generate an Index using
this function.


To set the output file for the table of contents, use the SetTOCFile function
prior to calling Generate. To set the output file for the index, use the
SetIndexFile function prior to calling Generate.

Syntax
Generate(Which)
Which may be one of the following:
    GenTOC (101) - Generate the TOC
    GenIndex (102) - Generate the Index
    GenBoth (100) - Generate both the TOC and the Index
This parameter can be zero. If you are in a master document, no index or TOC is
generated. The files open and the page numbers update.

To display the dialog box and allow the user to decide which table(s) to
generate: Generate

Return Value
1   (TRUE) if the table was generated.
0   (UserCancel) if the user canceled the function.
 -2  (GeneralFailure) if the table could not be generated.

Example
FUNCTION Example()
Generate(100)
END FUNCTION

See also:

    MarkIndexWord
    SetIndexFile
    SetTOCFile


ΓòÉΓòÉΓòÉ 158. GetAmiDirectory ΓòÉΓòÉΓòÉ

This function returns the path from which Ami Pro is currently running.


Syntax
GetAmiDirectory$()

Return Value
A string containing the path where Ami Pro is currently running, with a
trailing backslash.

Example
FUNCTION Example()
AmiDir = GetAmiDirectory$()
CurDir = GetCurrentDir$()
DocPath = GetDocPath$()
StylePath = GetStylePath$()
MacPath = GetMacPath$()
Message("Ami Pro is in {AmiDir}.")
Message("DOS reports the current directory is {CurDir}.")
Message("Ami Pro's default doc path is {DocPath}.")
Message("Ami Pro's default macro path is {MacPath}.")
Message("Ami Pro's default style path is {StylePath}.")
END FUNCTION

See also:

    GetBackPath$
    GetDocPath$
    GetHomeDirectory$
    GetMacPath$
    GetStylePath$


ΓòÉΓòÉΓòÉ 159. GetBackPath ΓòÉΓòÉΓòÉ

This function returns the default path for backup files.


Syntax
GetBackPath$()

Return Value
A string with the current default document backup path, with a trailing
backslash.

Example
FUNCTION Example()
AmiDir = GetAmiDirectory$()
CurDir = GetCurrentDir$()
DocPath = GetDocPath$()
StylePath = GetStylePath$()
BackPath = GetBackPath$()
MacPath = GetMacPath$()
Message("Ami Pro is in {AmiDir}.")
Message("DOS reports the current directory is {CurDir}.")
Message("Ami Pro's default doc path is {DocPath}.")
Message("Ami Pro's default macro path is {MacPath}.")
Message("Ami Pro's default style path is {StylePath}.")
Message("Ami Pro's default backup path is {BackPath}.")
END FUNCTION

See also:

    GetAmiDirectory$
    GetCurrentDir$
    GetDocPath$
    GetHomeDirectory$
    GetMacPath$
    GetStylePath$
    SetBackPath
    SetDocPath
    SetStylePath



ΓòÉΓòÉΓòÉ 160. GetBookMarkCount ΓòÉΓòÉΓòÉ

This function is used to dimension the arrays for the GetBookMarkNames
function.


Syntax
GetBookMarkCount()

Return Value
The number of bookmarks in the current document.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
Count = GetBookMarkCount()
IF Count > 0
    DIM BookMarks(Count)
    GetBookMarkNames(&BookMarks)
    DeleteMenu(1, "&BookMarks")
    AddMenu(1, "&BookMarks")
    FOR I = 1 to Count
       ThisBookMark = BookMarks(I)
       AddMenuItem(1, "&BookMarks", ThisBookMark, "{MacFile}!Example2(
 {ThisBookMark})", ThisBookMark)
    NEXT
ELSE
    Message("No bookmarks in this document!")
ENDIF
END FUNCTION

FUNCTION Example2(Bkmk)
BookPage = GetBookMarkPage(Bkmk)
Message("Now going to {Bkmk} on page {BookPage}.")
MarkBookMark(Bkmk, FindBookMark)
END FUNCTION

See also:

    GetBookMarkNames
    GoToCmd
    MarkBookMark





ΓòÉΓòÉΓòÉ 161. GetBookMarkNames ΓòÉΓòÉΓòÉ

This function shows the names of the arrays that are to receive the bookmark
names.


Syntax
GetBookMarkNames(&Array)
&Array is the names of the arrays. Note the use of indirection (&).

Return Value
The number of bookmark names.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
Count = GetBookMarkCount()
IF Count > 0
    DIM BookMarks(Count)
    GetBookMarkNames(&BookMarks)
    DeleteMenu(1, "&BookMarks")
    AddMenu(1, "&BookMarks")
    FOR I = 1 to Count
       ThisBookMark = BookMarks(I)
       AddMenuItem(1, "&BookMarks", ThisBookMark, "{MacFile}!Example2(
 {ThisBookMark})", ThisBookMark)
    NEXT
ELSE
    Message("No bookmarks in this document!")
ENDIF
END FUNCTION

FUNCTION Example2(Bkmk)
BookPage = GetBookMarkPage(Bkmk)
Message("Now going to {Bkmk} on page {BookPage}.")
MarkBookMark(Bkmk, FindBookMark)
END FUNCTION

See also:

    GetBookMarkCount
    GoToCmd
    MarkBookMark



ΓòÉΓòÉΓòÉ 162. GetBookMarkPage ΓòÉΓòÉΓòÉ

This function finds the page number where the specified bookmark begins. This
number is relative only to the current document. If the file is one file of a
master document, you must use the PhysicalToLogical function to determine the
printed page number.


Syntax
GetBookMarkPage(Name)
Name is the name of the bookmark (in the current document) whose page you want
to find.

Return Value
The page number on which the specified bookmark begins.
-2  if the bookmark could not be found.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
Count = GetBookMarkCount()
IF Count > 0
    DIM BookMarks(Count)
    GetBookMarkNames(&BookMarks)
    DeleteMenu(1, "&BookMarks")
    AddMenu(1, "&BookMarks")
    FOR I = 1 to Count
       ThisBookMark = BookMarks(I)
       AddMenuItem(1, "&BookMarks", ThisBookMark, "{MacFile}!Example2(
 {ThisBookMark})", ThisBookMark)
    NEXT
ELSE
    Message("No bookmarks in this document!")
ENDIF
END FUNCTION

FUNCTION Example2(Bkmk)
BookPage = GetBookMarkPage(Bkmk)
Message("Now going to {Bkmk} on page {BookPage}.")
MarkBookMark(Bkmk, FindBookMark)
END FUNCTION

See also:

    GetBookMarkNames
    GetBookMarkCount
    GetPageNo
    GoToCmd
    MarkBookMark
    PhysicalToLogical





ΓòÉΓòÉΓòÉ 163. GetCurFontInfo ΓòÉΓòÉΓòÉ

This function returns information about the current font at the insertion
point.


Syntax
GetCurFontInfo(&Name, &Color, &Size, &PitchFamily)
Name is the name of the font.
Color is the color of the font.
Size is the size of the font in twips (1 inch = 1440 twips).
PitchFamily is the bit value containing Pitch and Family. To extract these, use
the bitwise operator OR (|).
Note the use of indirection (&).

Return Value
This function does not return a value.

Example
FUNCTION Example()
DEFSTR Name, Color, Size, Family;
' get the current font information
GetCurFontInfo(&Name, &Color, &Size, &Family)
' increase pointsize by two and calculate the twips
Size = ((Size / 20) + 2) * 20
' change font
FontChange(Name, Family, Color, Size)
END FUNCTION

See also:

    FontChange
    FontFaceChange
    FontPointSizeChange
    FontRevert


ΓòÉΓòÉΓòÉ 164. GetCurFrameBorders ΓòÉΓòÉΓòÉ

This function finds the frame border information for the selected frame.


Syntax
GetCurFrameBorders(&Width, &Height, &Top, &Left, &LeftMargin, &TopMargin,
&RightMargin, &BottomMargin)
Width is the width of the selected frame.
Height is the height of the selected frame.
Top is the vertical starting position of the frame.
Left is the horizontal starting position of the frame.
LeftMargin is the size of the left border of the frame.
TopMargin is the size of the top border of the frame.
RightMargin is the size of the right border of the frame.
BottomMargin is the size of the bottom border of the frame.
All values are returned in twips (1 inch = 1440 twips).
Note the use of indirection (&).

Return Value
This function does not return a value.

Example
FUNCTION Example()
DEFSTR Width, Height, Top, Left, LM, TM, RM, BM, Units;
' you must have a frame selected
WHILE not IsFrameSelected()
    UserControl("Please select a frame and choose Resume.")
WEND
' get the frame info
GetCurFrameBorders(&Width, &Height, &Top, &Left, &LM, &TM, &RM, &BM, &Units)
Message("The frame's dimensions are {Width} x {Height}.")
Message("The frame starts {Top} twips from the top of the page.")
Message("The frame starts {Left} twips from the left edge of the page.")
Message("The margins (in twips) of the frame are (T,B,L,R): {TM}, {BM}, {LM},
{RM}")
END FUNCTION

See also:

    AddFrame
    AddFrameDlg
    FrameLayout
    FrameModBorders
    FrameModColumns
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType


ΓòÉΓòÉΓòÉ 165. GetCurFrameLines ΓòÉΓòÉΓòÉ

This function finds information pertaining to the lines and shadows of the
selected frame.


Syntax
GetCurFrameLines(&BorderWhere, &PosType, &ThickType, &ShadeType, &BackType,
&ShadowColor, &ShadowLeft, &ShadowTop, &ShadowRight, &ShadowBottom)
BorderWhere is the lines around a frame. It is one of the following values:
    1 - All
    2 - Left
    4 - Right
    8 - Top
    16 - Bottom
PosType is the position of the border around a frame. It is one of the
following values:
    1 - Middle
    2 - Inside
    3 - Outside
    4 - Close to Inside
    5 - Close to outside
You can only choose one value for the PosType parameter.
ThickType is the thickness of the border. It is one of the following values:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rule
    DoubleTwoPoint (9) - Parallel two point rule
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
ShadeType sets the line color. It can be one of the following values:
    Black - 0
    Blue - 16727905
    Cyan - 16776960
    Green - 65280
    Magenta - 16711935
    MedBlue - 16744448
    Orange - 33279
    Pink - 8388863
    Purple - 16711809
    Red - 255
    White - 16777215
    Yellow - 65535
BackType sets the background color. It can be one of the values listed under
ShadeType.
ShadowColor sets the color for the frame shadow. It can be one of the values
listed under ShadeType.
ShadowLeft is the distance that the shadow is offset from the left side of the
frame in twips (1 inch = 1440 twips). It can be one of the following values or
a custom value:
    None (0) - No shadow
    Shallow (57) - Shallow shadow
    Normal (100) - Normal shadow
    Deep (172) - Deep shadow
ShadowTop is the distance that the shadow is offset from the top of the frame
in twips (1 inch = 1440 twips). It can be one of the values listed under
ShadowLeft or a custom value.
ShadowRight is the distance that the shadow is offset from the right side of
the frame in twips (1 inch = 1440 twips). It can be one of the values listed
under ShadowLeft or a custom value.
ShadowBottom is the distance that the shadow is offset from the bottom of the
frame in twips (1 inch = 1440 twips). It can be one of the values listed under
ShadowLeft or a custom value.
Note  The Use Of Indirection (&).

Return Value
This function does not return a value.

Example
FUNCTION Example()
DEFSTR Border, Pos, Thick, Shade, Background, ShadowColor, SL, ST, SR, SB;
' you must have a frame selected
WHILE not IsFrameSelected()
    UserControl("Please select or create frame.")
WEND
' get the frame info
GetCurFrameLines(&Border, &Pos, &Thick, &Shade, &Background, &ShadowColor, &SL,
&ST, &SR, &SB)
TYPE("[ESC]Frame Border: {Border}[Enter]Frame Pos: {Pos}[Enter]")
TYPE("Line Thickness: {Thick}[Enter]Line Shading: {Shade}[Enter]")
TYPE("Shadow Background: {Background}[Enter]Bkgrnd Color:
{ShadowColor}[Enter]")
TYPE("Shadow Left: {SL}[Enter]Shadow Right: {SR}[Enter]")
TYPE("Shadow Top: {ST}[Enter]Shadow Bottom: {SB}[Enter]")
END FUNCTION

See also:

    AddFrame
    AddFrameDlg
    FrameLayout
    FrameModBorders
    FrameModColumns
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType



ΓòÉΓòÉΓòÉ 166. GetCurFrameType ΓòÉΓòÉΓòÉ

This function finds information about the type of frame, the roundness of the
frame, and the macro assigned to the frame.


Syntax
GetCurFrameType(&Type, &Rounded, &MacroName)
Type is the frame type.
Rounded is the amount that the corners are rounded, in percent. (0% is a square
and 100% is a circle).
MacroName is the name, if any, of the macro attached to this frame.

Return Value
This function does not return a value.

Example
FUNCTION Example()
DEFSTR Type, Rounded, MacroName;
' you must have a frame selected
WHILE not IsFrameSelected()
    UserControl("Please select or create a frame.")
WEND
' get the frame info
GetCurFrameType(&Type, &Rounded, &MacroName)
Message("The type number of this frame is {Type}.")
Message("The percentage of corner rounding on this frame is {Rounded}.")
IF MacroName != ""
    Message("The macro attached to this frame is {MacroName}.")
ELSE
    Message("There is no macro attached to this frame.")
ENDIF
END FUNCTION

See also:

    AddFrame
    AddFrameDlg
    FrameLayout
    FrameModBorders
    FrameModColumns
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType


ΓòÉΓòÉΓòÉ 167. GetCurrentDir ΓòÉΓòÉΓòÉ

This function returns the current working directory as seen by Ami Pro.


Syntax
GetCurrentDir$()

Return Value
A string with the current working directory, including a trailing backslash.

Example
FUNCTION Example()
AmiDir = GetAmiDirectory$()
CurDir = GetCurrentDir$()
DocPath = GetDocPath$()
StylePath = GetStylePath$()
MacPath = GetMacPath$()
Message("Ami Pro is in {AmiDir}.")
Message("DOS reports the current directory is {CurDir}.")
Message("Ami Pro's default doc path is {DocPath}.")
Message("Ami Pro's default macro path is {MacPath}.")
Message("Ami Pro's default style path is {StylePath}.")
END FUNCTION

See also:

    GetAmiDirectory$
    GetBackPath$
    GetDocPath$
    GetHomeDirectory$
    GetMacPath$
    GetStylePath$




ΓòÉΓòÉΓòÉ 168. GetDialogField ΓòÉΓòÉΓòÉ

This function is used to retrieve the contents of a dialog box field that has
been displayed in the last DialogBox function call.


Before using this function, ensure that the user did not cancel out of the
DialogBox function, or the results of this function are invalid.

Syntax
GetDialogField$(ID)
ID is the ID Number of the field whose value is being retrieved, as defined in
the resource file.

Return Value
Up to an 80 byte string if the field is an edit box, a list box, or a combo
box.
0  (FALSE) if the object was a button and was not checked or selected.
1  (TRUE) if the object was a button and was checked or selected.

Example
FUNCTION Example()
Filledit(20,1)       ' Turn apples on
Filledit(8000,"Bob") ' Put text in Edit Box
Filledit(9001,"*.sam")
Box = DialogBox(".","ExampleBox")
IF Box<>1
    EXIT FUNCTION
ENDIF
Store = GetdialogField$(22)    ' Retrieve Combo Box
File = GetdialogField$(9001)       ' Retrieve List Box result
Name = GetDialogField$(8000)   ' Retrieve Edit Box
Dir = GetCurrentDir$()      ' Get current directory
Message("Goto Store = {Store} Name ={Name} File = {File}")
END FUNCTION

DIALOG ExampleBox
-2134376448 10 71 44 115 98 "" "" "Sample Dialog Box"
FONT 8 "Helv"
69 3 40 14 1 1342373889 "button" "OK" 0
69 19 40 14 2 1342373888 "button" "Cancel" 0
6 24 52 56 9001 1352728579 "listbox" "" 0
6 13 40 10 7999 1342177280 "static" "" 0
6 4 40 10 1001 1342177280 "static" "&Files:" 0
69 37 37 12 20 1342242825 "button" "&Apples" 0
69 49 42 12 21 1342242825 "button" "&Oranges" 0
6 83 45 12 22 1342242819 "button" "&Goto Store" 0
69 61 42 12 23 1342242825 "button" "&Soap" 0
69 82 43 12 8000 1350631552 "edit" "" 0
END DIALOG

See also:

    DialogBox
    FillEdit
    FillList
    GetDLGItem
    GetDLGItemText
    SetDLGCallback
    SetDLGItemText


ΓòÉΓòÉΓòÉ 169. GetDlgItem ΓòÉΓòÉΓòÉ

This function returns the OS/2 window handle to the specified control or
object.


Syntax
GetDlgItem(Handle, ID)
Handle is the handle to the dialog box, passed to a callback function.
ID is the ID number of the object for which you want to get the handle.

Return Value
The OS/2 window handle for the specified control or object.

Example
FUNCTION Example()
' get the name of this macro file
MacFile = GetRunningMacroFile$()
' run ClearBox if the Re-Fill box is pressed
SetDlgCallBack(50, "{MacFile}!ClearBox")
FOR I = 1 to 10
    FillEdit(9000, I)' fill the edit box
NEXT
Box = DialogBox(".", "ExampleBox")    ' display the example box
END FUNCTION

FUNCTION ClearBox(hdlg, id, text)
' get the handle to the list box
handle = GetDlgItem(hdlg, 9000)
AppSendMessage(handle, 0x0405, 0, 0)
Message("Cleared List Box, Now I Will Re-Fill It...")
FOR I = 1 to 10
    SetDlgItemText(hdlg, 9000, I)
NEXT
END FUNCTION

DIALOG ExampleBox
-2134376448 4 169 46 106 76 "" "" "Example Dialog Box"
FONT 6 "Helv"
62 3 40 14 2 1342242817 "button" "DONE" 0
62 19 40 14 50 1342242816 "button" "Re-Fill Box" 0
4 11 52 61 9000 1352728579 "listbox" "" 0
5 2 51 9 1000 1342177280 "static" "Number:" 0
END DIALOG

See also:

    DialogBox
    FillEdit
    FillList
    GetDLGItemText
    SetDLGCallback
    SetDLGItemText



ΓòÉΓòÉΓòÉ 170. GetDlgItemText ΓòÉΓòÉΓòÉ

This function returns the contents of a dialog box object field.


Syntax
GetDlgItemText(Handle, ID)
Handle is the handle to the dialog box, passed to a CallBack function.
ID is the ID number of the desired object. If the ID is a radio button or check
box, the text returns a TRUE or FALSE condition.

Return Value
The contents of the specified object.
If the object is a button, this function returns a TRUE or FALSE value.
If the object is an edit box, a list box, or a combo box, this function returns
a string.

Example
FUNCTION Example()
' get the name of this macro file
MacFile = GetRunningMacroFile$()
' run Message1 function when Run Example is pressed
SetDlgCallBack(50, "{MacFile}!Message1")
' ExampleBox is in this file
Box = DialogBox(".", "ExampleBox")
IF Box = -1
    Message("Could not find dialog box!")
    EXIT FUNCTION
ELSEIF Box = 0
    EXIT FUNCTION
ENDIF
' type the name backwards into a document
TYPE(GetDialogField$(8002))
END FUNCTION

FUNCTION Message1(hdlg, id, text)
' get the type in name
Name = GetDlgItemText(hdlg, 8000)
Message("The contents of the first box are {Name}.")
Message("We will now fill the second box with the inverse of {Name}.")
' reverse the name
FOR I = len(Name) to 1 step -1
    Name2 = strcat$(Name2, MID$(Name, I, 1))
NEXT
' fill the second edit box
SetDlgItemText(hdlg, 8002, Name2)
END FUNCTION

DIALOG ExampleBox
-2134376448 8 106 38 160 54 "" "" "Sample Dialog Box"
FONT 6 "Helv"
50 6 62 12 8000 1350631552 "edit" "" 0
4 6 44 10 1000 1342177280 "static" "Your Name:" 0
50 20 62 12 1003 1342177287 "static" "" 0
4 22 44 10 1002 1342177280 "static" "Reversed:" 0
52 22 58 8 8002 1342177280 "static" "" 0
116 4 40 14 1 1342242817 "button" "OK" 0
116 20 40 14 2 1342242816 "button" "Cancel" 0
100 36 56 14 50 1342242816 "button" "&Run Example..." 0
END DIALOG

See also:

    DialogBox
    FillEdit
    FillList
    GetDialogField$
    GetDlgItem
    SetDlgCallback


ΓòÉΓòÉΓòÉ 171. GetDocInfo ΓòÉΓòÉΓòÉ

This function retrieves one of the document information fields from the current
document.


Syntax
GetDocInfo$(Which)
Which is the desired document info field to retrieve and may be one of the
following:
    DDFilename (1) - File name
    DDPath (2) - Path for this document
    DDStylesheet (3) - Style sheet for this document
    DDCreated (4) - Date document was created
    DDRevised (5) - Date document was revised
    DDRevisions (6) - Number of document revisions
    DDDescription (7) - Document info
    DDUser1 (8) - User  Defined Field 1
    DDUser2 (9) - User defined Field 2
    DDUser3 (10) - User defined Field 3
    DDUser4 (11) - User defined Field 4
    DDUser5 (12) - User defined Field 5
    DDUser6 (13) - User defined Field 6
    DDUser7 (14) - User defined Field 7
    DDUser8 (15) - User  Defined Field 8

Return Value
A string containing the desired document info field.

Example
FUNCTION Example()
DIM Field(15)
Message("Ready to type the contents of the Doc Info fields into the document.")
FOR I = 1 to 15
    Field(I) = GetDocInfo$(I)
NEXT
' put the field values in variables
Filename = Field(1)
Path = Field(2)
Style = Field(3)
Created = Field(4)
Revised = Field(5)
Number = Field(6)
Descrip = Field(7)
TYPE("The current filename is {Filename}.[Enter]")
TYPE("The path for this document is {Path}.[Enter]")
TYPE("The style sheet for this document is {Style}.[Enter]")
TYPE("This document was created on {Created}.[Enter]")
TYPE("This document was last revised on {revised}.[Enter]")
TYPE("This document has been revised {Number} times.[Enter]")
TYPE("The document description for this document states:[Enter]
{Descrip}.[Enter]")
FOR I = 1 to 8
    ThisField = Field(I + 7)
    IF ThisField != ""
       TYPE("User defined field {I} of this document contains:
 {ThisField}.[Enter]")
    ELSE
       TYPE("User defined field {I} contains nothing.[Enter]")
    ENDIF
NEXT
END FUNCTION

See also:

    DocInfo
    GetDocInfoKeywords$
    InsertDocInfoField
    InsertDocInfo
    RenameDocInfoField


ΓòÉΓòÉΓòÉ 172. GetDocInfoKeywords ΓòÉΓòÉΓòÉ

This function returns the keywords field from the Doc Info dialog box.


Syntax
GetDocInfoKeywords$()

Return Value
This function returns the Keywords field.

Example
FUNCTION Example()
Words=GetDocInfoKeywords$()
Message ("The Keywords for this doc are:{Words}.")
END FUNCTION

See also:

    DocInfo
    GetDocInfo$
    InsertDocInfoField
    InsertDocInfo
    RenameDocInfoField


ΓòÉΓòÉΓòÉ 173. GetDocPath ΓòÉΓòÉΓòÉ

This function returns the drive and directory of the default document storage
path.


Syntax
GetDocPath$()

Return Value
A string containing the current default document path, with a trailing
backslash.

Example
FUNCTION Example()
AmiDir = GetAmiDirectory$()
CurDir = GetCurrentDir$()
DocPath = GetDocPath$()
StylePath = GetStylePath$()
MacPath = GetMacPath$()
Message("Ami Pro is in {AmiDir}.")
Message("DOS reports the current directory is {CurDir}.")
Message("Ami Pro's default doc path is {DocPath}.")
Message("Ami Pro's default macro path is {MacPath}.")
Message("Ami Pro's default style path is {StylePath}.")
END FUNCTION

See also:

    GetAmiDirectory$
    GetBackPath$
    GetCurrentDir$
    GetHomeDirectory$
    GetMacPath$
    GetStylePath$
    SetBackPath
    SetDocPath
    SetStylePath



ΓòÉΓòÉΓòÉ 174. GetDocVar ΓòÉΓòÉΓòÉ

This function returns the value associated with Name. Document variables are
kept with the current document. Document variables have a name and a value.
They can be retrieved by name using this function or all document variables can
be returned using the GetPowerFields function.


Syntax
GetDocVar(Name)
Name is the name of the document variable to retrieve.

Return Value
A string containing the information in the document variable.

Example
FUNCTION Example()
val = GetDocVar("answer1")
END FUNCTION

See also:

    GetPowerFields
    SetDocVar


ΓòÉΓòÉΓòÉ 175. GetFmtPageStr ΓòÉΓòÉΓòÉ

This function returns the page number of a bookmark and the paragraph style
that page number is currently using.


Syntax
GetFmtPageStr$(Name)
Name is the name of the Bookmark for which to find the page number.

Return Value
A string containing the page on which the specified bookmark begins, including
the paragraph style the page number is using.

Example
FUNCTION Example()
Bkmk = Query$("What is the name of the bookmark to use?")
Page = GetFmtPageStr$(Bkmk)
Message("The page, with formatting that {Bkmk} is on is {Page}.")
END FUNCTION

See also:

    GetBookMarkCount
    GetBookMarkNames
    GetBookMarkPage
    GetPageNo
    GoToCmd
    MarkBookMark


ΓòÉΓòÉΓòÉ 176. GetGlobalArray ΓòÉΓòÉΓòÉ

This function returns a global array element.


Global variables cannot be directly used by functions and statements. Their
values must be assigned to local variables before they can be used.

Syntax
GetGlobalArray$(Name, Index)
Name is the name or the number of the global variable to use.
Index is the element of the global array you are retrieving.

Return Value
The value of the global array element.

Example
FUNCTION Example()
AllocGlobalVar("Names", 5)'Allocate space for a 5 element global variable
AllocGlobalVar("Numbers", 5)'Allocate space for a 5 element global variable
AllocGlobalVar("YourName", 1)'Allocate space for a single element global
variable.
FOR I = 1 to 5'Do the following 5 times.
SetGlobalArray("Names", I, Query$("Enter Name Number {I}"))
'Fill a global array with the return from QUERY
SetGlobalArray("Numbers", I, (100/I))'Fill a global array with a number
NEXT
NewName = Query$("What is your name?")'Query the user for his/her name
SetGlobalVar("YourName", NewName)'Set a global variable to that value
CALL Example2()'Call the following function
END FUNCTION

FUNCTION Example2()
Name = GetGlobalVar$("YourName")'Get the value of the global variable
Message("Your name is {Name}.")'Message that value in a box.
FOR I = 1 to 5'Do the following 5 times.
TheirName = GetGlobalArray$("Names", I)'Get the value of the current element
from the array
TheirNumber = GetGlobalArray$("Numbers", I)'Get the value of the current
element from the array
TYPE("Name #{I} is {TheirName}, and the number is {TheirNumber}.[Enter]")
'Type the values to the screen.
NEXT
FreeGlobalVar("Names")'Clear the space for the first global array
FreeGlobalVar("Numbers")'Clear the space for the second global array
FreeGlobalVar("YourName")'Clear the space for the global variable
END FUNCTION

See also:

    AllocGlobalVar
    FreeGlobalVar
    GetGlobalVar$
    SetGlobalArray
    SetGlobalVar
    Using Variables



ΓòÉΓòÉΓòÉ 177. GetGlobalVar ΓòÉΓòÉΓòÉ

This function returns a global array variable.


Global variables cannot be directly used by functions and statements. Their
values must be assigned to local variables before they can be used.

Syntax
GetGlobalVar$(Name)
Name is the name or the number of the global variable to retrieve the data
from.

Return Value
The value of the global variable.

Example
FUNCTION Example()
AllocGlobalVar("Name", 1)
AllocGlobalVar("Computer", 1)
AllocGlobalVar("Software", 1)
Name = Query$("What is your name?")
Computer = Query$("What kind of computer do you have?")
Software = Query$("What is your favorite piece of software?")
SetGlobalVar("Name", Name)
SetGlobalVar("Computer", Computer)
SetGlobalVar("Software", Software)
CALL Example2()'Call the following function
END FUNCTION

FUNCTION Example2()
NumGlobs = GetGlobalVarCount()
DIM TempArray(Numglobs)
GetGlobalVarNames(&TempArray)
FOR i = 1 to NumGlobs
    VarName=TempArray(i)
    VarContents=GetGlobalVar$(VarName)
    TYPE ("Item {i}, {VarName}, is {VarContents}.[ENTER]")
    FreeGlobalVar(VarName)
NEXT
END FUNCTION

See also:

    AllocGlobalVar
    FreeGlobalVar
    GetGlobalArray$
    SetGlobalArray
    SetGlobalVar
    Using Variables



ΓòÉΓòÉΓòÉ 178. GetGlobalVarCount ΓòÉΓòÉΓòÉ

This function returns the total number of global variables currently allocated.
It is used to dimension an array before calling the GetGlobalVarNames function.


Syntax
GetGlobalVarCount()

Return Value
The total number of global variables currently allocated.

Example
FUNCTION Example()
AllocGlobalVar("Name", 1)
AllocGlobalVar("Computer", 1)
AllocGlobalVar("Software", 1)
Name = Query$("What is your name?")
Computer = Query$("What kind of computer do you have?")
Software = Query$("What is your favorite piece of software?")
SetGlobalVar("Name", Name)
SetGlobalVar("Computer", Computer)
SetGlobalVar("Software", Software)
CALL Example2()'Call the following function
END FUNCTION

FUNCTION Example2()
NumGlobs = GetGlobalVarCount()
DIM TempArray(Numglobs)
GetGlobalVarNames(&TempArray)
FOR i = 1 to NumGlobs
    VarName=TempArray(i)
    VarContents=GetGlobalVar$(VarName)
    TYPE ("Item {i}, {VarName}, is {VarContents}.[ENTER]")
    FreeGlobalVar(VarName)
NEXT
END FUNCTION

See also:

    AllocGlobalVar
    GetGlobalArray$
    GetGlobalVar$
    GetGlobalVarNames
    SetGlobalArray
    SetGlobalVar


ΓòÉΓòÉΓòÉ 179. GetGlobalVarNames ΓòÉΓòÉΓòÉ

This function finds the names or ID numbers of all of the currently allocated
global variables.


Syntax
GetGlobalVarNames(&Array)
Array is the name of the array to place the names or ID numbers of the
currently allocated global variables.
Note the use of indirection (&).

Return Value
The number of global variances.

Example
FUNCTION Example()
AllocGlobalVar("Name", 1)
AllocGlobalVar("Computer", 1)
AllocGlobalVar("Software", 1)
Name = Query$("What is your name?")
Computer = Query$("What kind of computer do you have?")
Software = Query$("What is your favorite piece of software?")
SetGlobalVar("Name", Name)
SetGlobalVar("Computer", Computer)
SetGlobalVar("Software", Software)
CALL Example2()'Call the following function
END FUNCTION

FUNCTION Example2()
NumGlobs = GetGlobalVarCount()
DIM TempArray(Numglobs)
GetGlobalVarNames(&TempArray)
FOR i = 1 to NumGlobs
    VarName=TempArray(i)
    VarContents=GetGlobalVar$(VarName)
    TYPE ("Item {i}, {VarName}, is {VarContents}.[ENTER]")
    FreeGlobalVar(VarName)
NEXT
END FUNCTION

See also:

    AllocGlobalVar
    GetGlobalArray$
    GetGlobalVar$
    GetGlobalVarCount
    SetGlobalArray
    SetGlobalVar


ΓòÉΓòÉΓòÉ 180. GetHomeDirectory ΓòÉΓòÉΓòÉ

This function returns the directory where Ami Pro stores the INI files. If you
are running Ami Pro on a standalone computer, this function returns the OS/2
directory. If you are running Ami Pro on a network, this function returns the
directory specified when the node was installed.


Syntax
GetHomeDirectory$()

Return Value
This function returns the OS/2 directory.

Example
FUNCTION Example()
homedir = GetHomeDirectory$()
Message("Home Directory is {homedir}.")
END FUNCTION

See also:

    GetAmiDirectory$
    GetDocPath$
    GetMacPath$
    GetStylePath$



ΓòÉΓòÉΓòÉ 181. GetIconPalette ΓòÉΓòÉΓòÉ

This function returns the name of the current SmartIcon set.


Syntax
GetIconPalette()

Return Value
A string containing the name of the icon set.

Example
FUNCTION Example()
palette = GetIconPalette()
Message("The icon palette is {palette}.")
END FUNCTION

See also:

    ChangeIcons
    IconBottom
    IconCustomize
    IconFloating
    IconLeft
    IconRight
    IconTop
    SetIconSize


ΓòÉΓòÉΓòÉ 182. GetLayoutLeftLines ΓòÉΓòÉΓòÉ

This function finds the current information about any lines associated with the
current page layout.


Syntax
GetLayoutLeftLines(&GutterShade, &GutterStyle, &BorderSides, &BorderStyle,
&BorderSpace)
GutterShade is the color of the line.
GutterStyle and BorderStyle define the width and type of the line and should be
one of the following:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rule
    DoubleTwoPoint (9) - Parallel two point rule
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
BorderSides is where the lines are placed on the page and can be one or more of
the following:
    (1) - All sides
    (2) - Left
    (4) - Right
    (8) - Top
    (16) - Bottom
To extract any combination, use the bitwise operator OR (|) on this number.
The Right value is also used when you have only one page format.
BorderSpace is how close the border is to the printed page and can be one of
the following:
    (1) - Middle
    (2) - Inside
    (3) - Outside
    (4) - Close to Inside
    (5) - Close to Outside
Note the use of indirection (&).

Return Value
This function does not return a value.

Example
FUNCTION Example()
DEFSTR Gshade, Gstyle, Bsides, Bstyle, Bspace;
' get the page layout line info
GetLayoutLeftLines(&Gshade, &Gstyle, &Bsides, &Bstyle, &Bspace)
TYPE("The color of the lines is: {Gshade}.[Enter]")
TYPE("The width of the gutter is: {Gstyle}.[Enter]")
TYPE("The lines are placed: {Bsides}.[Enter]")
TYPE("The style of the border is: {Bstyle}.[Enter]")
TYPE("The location of the lines is: {Bspace}.[Enter]")
END FUNCTION

See also:

    GetLayoutPageSize
    GetLayoutParameters
    GetLayoutType
    ModifyLayout


ΓòÉΓòÉΓòÉ 183. GetLayoutPageSize ΓòÉΓòÉΓòÉ

This function finds the page size information for the current page layout.


Syntax
GetLayoutPageSize(&Length, &Width, 0, 0)
Length is the length of the page, in twips (1 inch = 1440 twips).
Width is the width of the page, in twips.
Note the use of indirection (&).

Return Value
This function does not return a value.

Example
FUNCTION Example()
DEFSTR Length, Width;
' get the page size info
GetLayoutPageSize(&Length, &Width, 0, 0)
TYPE("The length of the page is {Length} twips.[Enter]")
TYPE("The width of the page is {Width} twips.[Enter]")
END FUNCTION

See also:

    GetLayoutLeftLines
    GetLayoutParameters
    GetLayoutType
    ModifyLayout


ΓòÉΓòÉΓòÉ 184. GetLayoutParameters ΓòÉΓòÉΓòÉ

This function finds the margin, columns, and tab information for the current
page layout.


Syntax
GetLayoutParameters(Which, &Parameters)
Which is the type of page layout you want to get information about. It can be
one of the following functions:
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftPage
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightPage
Parameters is an array that was dimensioned according to the return value of
GetLayoutParmCnt.
Note the use of indirection (&).

Return Value
This function does not return a value.

Example
FUNCTION Example()
' Get number of parameters for ModLayoutRightPage
Cnt = GetLayoutParmCnt(ModLayoutRightPage)
DIM Stuff(Cnt)       'Dimension an array for that amount
' Get the parameters and place in the array
GetLayoutParameters(ModLayoutRightPage, &Stuff)
' Query for new headers lengthh
length = Query$("New length of right/all headers?")
' Query for new headers height.
width = Query$("New width of right/all headers?")
Stuff(1) = length * 1440       'Turn into twips
Stuff(2) = width * 1440     'Turn into twips
' Prep Ami Pro to accept Layout changes for all pages
ModLayoutInit(512)
' Apply changes to specified function.
AmiProIndirect(ModLayoutRightPage, &Stuff, Cnt)
' Tell Ami Pro to accept the specified changes
ModLayoutFinish()
END FUNCTION

See also:

    GetLayoutLeftLines
    GetLayoutPageSize
    GetLayoutType
    ModifyLayout
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftPage
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightPage





ΓòÉΓòÉΓòÉ 185. GetLayoutType ΓòÉΓòÉΓòÉ

This function returns the type of  page layout for the current page layout.


Syntax
GetLayoutType()

Return Value
A bit number containing the values of the All pages bit and should be one of
the following:
    0 - Neither
    512 - All  Pages
    1536 - Both
To extract the individual bits, use the bitwise operator OR (|).

Example
FUNCTION Example()
Type = GetLayoutType()
IF Type & 0
    Type = "Neither all pages nor mirrored"
ELSEIF Type & 512
    Type = "All Pages"
ELSEIF Type & 1024
    Type = "Mirror Image"
ELSEIF Type & 1536
    Type = "Both all pages and mirror image"
ENDIF
Message("The current layout type is {Type}.")
END FUNCTION

See also:

    GetLayoutLeftLines
    GetLayoutPageSize
    GetLayoutParameters
    ModifyLayout


ΓòÉΓòÉΓòÉ 186. GetMacPath ΓòÉΓòÉΓòÉ

This function returns the drive and directory of the default macro directory
path.


Syntax
GetMacPath$()

Return Value
A string with the drive and directory of the default macro directory path.

Example
FUNCTION Example()
AmiDir = GetAmiDirectory$()
CurDir = GetCurrentDir$()
DocPath = GetDocPath$()
StylePath = GetStylePath$()
MacPath = GetMacPath$()
Message("Ami Pro is in {AmiDir}.")
Message("DOS reports the current directory is {CurDir}.")
Message("Ami Pro's default doc path is {DocPath}.")
Message("Ami Pro's default macro path is {MacPath}.")
Message("Ami Pro's default style path is {StylePath}.")
END FUNCTION

See also:

    GetBackPath$
    GetCurrentDir$
    GetDocPath$
    GetHomeDirectory$
    GetStylePath$


ΓòÉΓòÉΓòÉ 187. GETMARKTEXT ΓòÉΓòÉΓòÉ

This function gets the name of a bookmark, a merge field, contents of a note,
or a power field. Before using this function, the insertion point should be at
the location of a merge field, a bookmark, or a power field.


You should use the GoToCmd function for bookmarks, merge fields, notes, and
fields. Use the FieldNext function to set the insertion point.

Syntax
GetMarkText$()

Return Value
The name of the bookmark, merge field, or power field at the insertion point.
The null string ("") if the insertion point was not on one of these marks.

Example
FUNCTION Example()
MarkBookMark("Example", AddBookMark)
TYPE("[CtrlEND]")
MarkBookMark("Example", FindBookMark)
Text = GetMarkText$()
MarkBookMark("Example", DeleteBookMark)
IF Text != ""
    Message("Your bookmark was named ""{Text}"".")
ENDIF
END FUNCTION

See also:

    FieldAdd
    FieldNextFieldPrev
    GetTextBeforeCursor$
    GoToCmd
    MarkBookMark


ΓòÉΓòÉΓòÉ 188. GetMasterFiles ΓòÉΓòÉΓòÉ

This function fills an array with the names of any master file documents
associated with the current document. The array may be dimensioned using the
GetMasterFilesCount function.


Syntax
GetMasterFiles(&Array)
Array is the name of the array in which to place the names of the master files.
Note the use of indirection (&).

Return Value
The number of files.

Example
FUNCTION Example()
' get the number of associated documents
Count = GetMasterFilesCount()
IF Count > 1
    ' put the names in the File array
    DIM Files(Count)
    GetMasterFiles(&Files)
    FOR I = 1 to Count
       Message(Files(I))' display the names
    NEXT
ELSE
    Message("No master files!")
ENDIF
END FUNCTION

See also:

    AmiProIndirect
    GetMasterFilesCount
    SetMasterFiles


ΓòÉΓòÉΓòÉ 189. GetMasterFilesCount ΓòÉΓòÉΓòÉ

This function returns the total number of master files associated with the
current file. It is useful in dimensioning an array to hold the names of all of
the master files.


Syntax
GetMasterFilesCount()

Return Value
The number of master files associated with the current document.

Example
FUNCTION Example()
' get the number of associated documents
Count = GetMasterFilesCount()
IF Count > 1
    ' put the names in the File array
    DIM Files(Count)
    GetMasterFiles(&Files)
    FOR I = 1 to Count
       Message(Files(I))' display the names
    NEXT
ELSE
    Message("No master files!")
ENDIF
END FUNCTION

See also:

    AmiProIndirect
    GetMasterFiles
    SetMasterFiles


ΓòÉΓòÉΓòÉ 190. GetMode ΓòÉΓòÉΓòÉ

This function determines whether the program is in Layout Mode, Outline Mode,
or Draft Mode.


Syntax
GetMode()

Return Value
A number representing the current view mode:
    Layout (1) - Layout Mode
    Draft (16) - Draft Mode
    Outline (48) - Outline Mode

Example
FUNCTION Example()
Mode = GetMode()'What mode is the screen in?
IF Mode != 1
    LayoutMode()'If not Layout Mode, make it so.
ENDIF
END FUNCTION

See also:

    CustomView
    DraftMode
    EnlargedView
    FullPageView
    GetViewLevel
    LayoutMode
    OutlineMode
    StandardView


ΓòÉΓòÉΓòÉ 191. GetOpenFileCount ΓòÉΓòÉΓòÉ

This function finds the total number of documents currently open. It is useful
in dimensioning an array to hold the names of these files.


Syntax
GetOpenFileCount()

Return Value
The total number of documents this instance of Ami Pro currently has open.

Example
FUNCTION Example()
' get the number of open docs
Count = GetOpenFileCount()
IF Count > 0
    DIM Files(Count)
    ' put the files names in the Files array
    GetOpenFileNames(&Files)
    FOR I = 1 to Count
       Message(Files(I))    'display the names
    NEXT
ELSE
    Message("No open files!")
ENDIF
END FUNCTION

See also:

    FileClose
    FileOpen
    GetOpenFileName$
    GetOpenFileNames
    SaveAs
    Save


ΓòÉΓòÉΓòÉ 192. GetOpenFileName ΓòÉΓòÉΓòÉ

This function retrieves the full path of the current document. If more than one
document is open, the name of the file with the focus is returned.


Syntax
GetOpenFileName$()

Return Value
The path of the open file.
The null string ("") if the current file is "Untitled".

Example
FUNCTION Example()
OpenFile = GetOpenFileName$()
Message("The current file is {OpenFile}.")
END FUNCTION

See also:

    GetCurrentDir$
    GetDocInfo$
    GetDocPath$
    GetMacPath$
    GetOpenFileNames
    SetDocPath


ΓòÉΓòÉΓòÉ 193. GetOpenFileNames ΓòÉΓòÉΓòÉ

This function fills an array with the names of all open Ami Pro documents. The
array may be dimensioned using the GetOpenFileCount function.


Syntax
GetOpenFileNames(&Array)
&Array is the name of the array in which to place the list of open files.
Untitled files return the empty string ("").

Return Value
1  (TRUE) if the array was filled.
0  (FALSE) if the array was not filled.

Example
FUNCTION Example()
' get the number of open docs
Count = GetOpenFileCount()
IF Count > 0
    DIM Files(Count)
    ' put the file names in the Files array
    GetOpenFileNames(&Files)
    FOR I = 1 to Count
       Message(Files(I))    'display the names
    NEXT
ELSE
    Message("No open files!")
ENDIF
END FUNCTION

See also:

    GetOpenFileCount
    FileClose
    FileOpen
    Save
    SaveAs
    GetOpenFileName$



ΓòÉΓòÉΓòÉ 194. GetPageNo ΓòÉΓòÉΓòÉ

This function retrieves the page number of the displayed page of the current
document.


Syntax
GetPageNo()

Return Value
The number of the displayed page of the current document.

Example
FUNCTION Example()
TYPE("[CtrlEND]")
PageNo = GetPageNo()
Message("There are {PageNo} pages in this document.")
END FUNCTION

See also:

    GetMode
    AtEOF
    GetFmtPageStr$
    GetBookMarkPage


ΓòÉΓòÉΓòÉ 195. GetPowerFieldCount ΓòÉΓòÉΓòÉ

This function returns the total number of power fields.


Syntax
GetPowerFieldCount(0)

Return Value
The number of power fields.

Example
FUNCTION Example()
type = 0
' get the number of power fields
Count = GetPowerFieldCount(type)
IF Count > 0
    DIM Power(Count)
    ' get the power fields
    GetPowerFields(type, &Power)
    FOR i = 1 to Count
       ' get the id from the power field
       pfid = strfield$(Power(i), 1, ",")
       pftype = strfield$(Power(i), 2, ",")
       pageno = GetPowerFieldPage(pfid, pftype)
       message("Power Field #{i} type {pftype} is on page {pageno}.")
    NEXT
ELSE
    message("No power fields in this document.")
ENDIF
END FUNCTION

See also:

    GetPowerFieldPage
    GetPowerFields
    GoToPowerField


ΓòÉΓòÉΓòÉ 196. GetPowerFieldPage ΓòÉΓòÉΓòÉ

This function returns the page number of a specific power field.


Syntax
GetPowerFieldPage(ID, 0)
ID is the number assigned to a specific power field. You can obtain the ID of
the power field by using GetPowerFields.

Return Value
The page number of the specified power field.

Example
FUNCTION Example()
type = 0
' get the number of power fields
Count = GetPowerFieldCount(type)
IF Count > 0
    DIM Power(Count)
    ' get the power fields
    GetPowerFields(type, &Power)
    FOR i = 1 to Count
       ' get the id and type from the power field
       pfid = strfield$(Power(i), 1, ",")
       pftype = strfield$(Power(i), 2, ",")
       pageno = GetPowerFieldPage(pfid, pftype)
       message("Power Field #{i} type {pftype} is on page {pageno}.")
    NEXT
ELSE
    message("No power fields in this document.")
ENDIF
END FUNCTION

See also:

    GetPowerFieldCount
    GoToPowerField
    GetPowerFields


ΓòÉΓòÉΓòÉ 197. GetPowerFields ΓòÉΓòÉΓòÉ

This function fills an array with any power fields located in the current
document. You can dimension the array by using GetPowerFieldCount.


Syntax
GetPowerFields(Type, &Array)
Array is the name of the array in which to place the power fields. The format
returned in the array is "ID, type, power field." Document variables are only
returned when type 10 is specified. The format for document variables are
"name=value".
Note the use of indirection (&).

Return Value
The number of power fields returned in the array.

Example
FUNCTION Example()
Count = GetPowerFieldCount(0)  ' Get the User powerfields
If count <1
    Message("No powerfields are in this document.")
    Exit Function       ' No powerfields, Exit macro
Endif
DIM Power(Count)
GetPowerFields(0, &Power)
FOR i = 1 to Count
    pfid = strfield$(Power(i), 1, ",")
    pftype = strfield$(Power(i), 2, ",")
    pageno = GetPowerFieldPage(pfid, pftype)
NEXT
GoToPowerField(pfid, pftype)
END FUNCTION

See also:

    GetPowerFieldCount
    GetPowerFieldPage


ΓòÉΓòÉΓòÉ 198. GetProfileString ΓòÉΓòÉΓòÉ

This function retrieves an entry from a text file such as the AMIUSER3.INI
file.


Syntax
GetProfileString$(Section, Key[, FileName])
Section is the section in the file to look in. If this is the empty string
(""), the [Ami Pro] section is searched.
Key is the desired entry in the file. If this is zero (0), or a null string
(""), all the keys from the [Ami Pro] section are returned separated with a
tilde (~).
FileName is optional, and specifies the file to look in.

Return Value
A string with the contents of the entry.
The null string ("") if the entry doesn't exist.

Example
function Example()
'check for current measurement setting
units=GetProfileString$("AmiUser", "DefaultUnit", "amiuser3.ini")
message("Units are set to {units}.")
end function

See also:

    GetMacPath$
    WriteProfileString
    GetAmiDirectory$


ΓòÉΓòÉΓòÉ 199. GetRunningMacroFile ΓòÉΓòÉΓòÉ

This function returns the file name, including full path, of the currently
running macro. This function is useful in allowing a function to call another
function in the same file, even if the file name has been changed.


Syntax
GetRunningMacroFile$()

Return Value
A string containing the full path and file name of the currently running macro.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
MacName = GetRunningMacroName$()
Message("This macro file is {MacFile}.")
Message("This function is {MacName}.")
END FUNCTION

See also:

    GetMacPath$
    GetRunningMacroName$


ΓòÉΓòÉΓòÉ 200. GetRunningMacroName ΓòÉΓòÉΓòÉ

This function returns the name of the currently running macro function.


Syntax
GetRunningMacroName$()

Return Value
A string containing the name of the currently running macro function.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
MacName = GetRunningMacroName$()
Message("This macro file is {MacFile}.")
Message("This function is {MacName}.")
END FUNCTION

See also:

    GetMacPath$
    GetRunningMacroFile$


ΓòÉΓòÉΓòÉ 201. GetSpecialEffects ΓòÉΓòÉΓòÉ

This function returns the text located at the beginning of a paragraph style.
The text is the text that is specified in Style Modify Style and choosing
Bullets/Numbers.


Syntax
GetSpecialEffects$()

Return Value
The text that is located at the beginning of the paragraph style.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the special effects could not be retrieved.

Example
FUNCTION Example()
Effects = GetSpecialEffects$()
IF Effects = ""
    Message("There is no text in special effects on this paragraph.")
ELSE
    Message("{Effects} is appended to this style.")
ENDIF
END FUNCTION

See also:

    ModifyStyle
    ModifyLines
    ModifyAlignment
    ModifyReflow
    ModifyBreaks
    ModifySelect
    ModifyEffects
    ModifySpacing
    ModifyFont
    ModifyTable


ΓòÉΓòÉΓòÉ 202. GetStyleCount ΓòÉΓòÉΓòÉ

This function returns the number of paragraph styles in the current document.


Syntax
GetStyleCount()

Return Value
The number of paragraph styles in the current document.

Example
FUNCTION Example()
Count = GetStyleCount()
DIM Styles(Count)
GetStyleNames(&Styles)
END FUNCTION

See also:

    GetStyleNames


ΓòÉΓòÉΓòÉ 203. GetStyleName ΓòÉΓòÉΓòÉ

This function determines the name of the paragraph style assigned to the
current paragraph.


Syntax
GetStyleName$()

Return Value
A string with the name of the paragraph style.

Example
FUNCTION Example()
curstyle = GetStyleName$()
newstyle = "Number List"
SetStyle(newstyle)
TYPE("This is what the {newstyle} style looks like.[Enter]")
SetStyle(curstyle)
END FUNCTION

See also:

    ModifyStyle
    SelectStyle
    SetStyle


ΓòÉΓòÉΓòÉ 204. GetStyleNames ΓòÉΓòÉΓòÉ

This function fills an array with the names of the paragraph styles in the
current document. The array may be dimensioned using the GetStyleCount
function.


Syntax
GetStyleNames(&Array)
Array is the name of the array in which to place the names of the paragraph
styles.
Note the use of indirection (&).

Return Value
This function returns the paragraph style names.

Example
FUNCTION Example()
Count = GetStyleCount()
DIM Styles(Count)
GetStyleNames(&Styles)
END FUNCTION

See also:

    GetStyleCount


ΓòÉΓòÉΓòÉ 205. GetStylePath ΓòÉΓòÉΓòÉ

This function returns the drive and directory of the default style sheet path.


Syntax
GetStylePath$()

Return Value
A string containing the current default paragraph style sheet path.

Example
FUNCTION Example()
AmiDir = GetAmiDirectory$()
CurDir = GetCurrentDir$()
DocPath = GetDocPath$()
StylePath = GetStylePath$()
MacPath = GetMacPath$()
Message("Ami Pro is in {AmiDir}.")
Message("DOS reports the current directory is {CurDir}.")
Message("Ami Pro's default doc path is {DocPath}.")
Message("Ami Pro's default macro path is {MacPath}.")
Message("Ami Pro's default style path is {StylePath}.")
END FUNCTION

See also:

    GetBackPath$
    GetDocPath$
    GetHomeDirectory$
    GetMacPath$
    SetBackPath
    SetDocPath
    SetStylePath


ΓòÉΓòÉΓòÉ 206. GetTextBeforeCursor ΓòÉΓòÉΓòÉ

This function retrieves the text between the beginning of the paragraph the
insertion point is in and the insertion point.


Syntax
GetTextBeforeCursor$()

Return Value
A string with the contents of the paragraph prior to the insertion point.

Example
FUNCTION Example()
Text = GetTextBeforeCursor$()
Length = len(Text)
Message("You are {Length} characters into the current paragraph.")
END FUNCTION

See also:

    CurChar$
    CurShade$
    CurWord$
    GetMarkText$
    TYPE


ΓòÉΓòÉΓòÉ 207. GetTime ΓòÉΓòÉΓòÉ

This function determines the amount of time that has elapsed since OS/2 was
started.


Syntax
GetTime()

Return Value
The number of milliseconds since OS/2 was started.

Example
FUNCTION Example()
CurrentTime = GetTime()
Message("{CurrentTime} milliseconds since OS/2 was started.")
END FUNCTION

See also:

    Pause
    RunLater
    Now
    FormatDate$
    FormatTime$


ΓòÉΓòÉΓòÉ 208. GetViewLevel ΓòÉΓòÉΓòÉ

This function returns the current Layout Mode View level.


Syntax
GetViewLevel()

Return Value
A number representing the current view level:
    FullPage (201) - Full Page View
    Custom (202) - Custom View
    Standard (203) - Standard View
    Enlarged (204) - Enlarged View

Example
FUNCTION Example()
Level = GetViewLevel()
SWITCH Level
CASE 201
Level = "Full Page View"
CASE 202
Level = "Custom View"
CASE 203
Level = "Standard View"
CASE 204
Level = "Enlarged View"
ENDSWITCH
Message("The current view level is at {Level}.")
END FUNCTION

See also:

    GetMode
    DraftMode
    LayoutMode
    FullPageView
    CustomView
    StandardView
    EnlargedView
    FacingView


ΓòÉΓòÉΓòÉ 209. GetViewPrefLevel ΓòÉΓòÉΓòÉ

This function gets the custom view percent from the View View Preferences
function. It is used to change the custom view percent in the ViewPreferences
function.


This function must be used with the GetViewPrefOpts function.

Syntax
GetViewPrefLevel()

Return Value
The value of the view level which is a number from 10-400.

Example
FUNCTION TurnOffNotes()
Viewopts=GetViewPrefOpts() ' get the View Preferences options
Viewlevel=GetViewPrefLevel() ' get the View Preferences level
IF(Viewopts & 2048) ' notes turned on?
    Viewopts=Viewopts - 2048 ' turn notes display off in options
ENDIF
ViewPreferences(Viewopts, Viewlevel) ' set new options
END FUNCTION

See also:

    GetViewPrefOpts
    ViewPreferences


ΓòÉΓòÉΓòÉ 210. GetViewPrefOpts ΓòÉΓòÉΓòÉ

This function retrieves the current Options parameter from the View Preferences
function. This function is required to change the View Preferences in a macro
when you need to know the current options to modify that value.


You must get the view options as well as the view level using the
GetViewPrefLevel function to change View Preferences.

Syntax
GetViewPrefOpts()

Return Value
The value of the View Preferences option.

Example
FUNCTION TurnOffNotes()
Viewopts=GetViewPrefOpts() ' get the View Preferences options
Viewlevel=GetViewPrefLevel() ' get the View Preferences level
IF(Viewopts & 2048) ' notes turned on?
    Viewopts=Viewopts - 2048 ' turn notes display off in options
ENDIF
ViewPreferences(Viewopts, Viewlevel) ' set new options
END FUNCTION

See also:

    GetViewPrefLevel
    View Preferences



ΓòÉΓòÉΓòÉ 211. Glossary ΓòÉΓòÉΓòÉ

This function inserts the named glossary item into the document at the
insertion point. This function is equivalent to choosing Edit Insert Glossary
Record. To set the glossary file before inserting items, use the GlossSet
function.


Syntax
Glossary(Item)
Item is the name of the glossary item to insert.

To display the Glossary dialog box and allow the user to select the name of the
glossary item to insert: Glossary

Return Value
1  (TRUE) if a glossary item was inserted.
0  (UserCancel) if the user canceled the menu function.
-2  (GeneralFailure) if the item could not be inserted or if the item was not
found.

Example
FUNCTION Example()
Gloss = Query$("What glossary file do you want to use?")
GlossSet(Gloss)
Glossary
END FUNCTION

See also:

    GlossaryAdd
    GlossaryClose
    GlossaryLookup
    GlossaryOpen
    GlossSet



ΓòÉΓòÉΓòÉ 212. GlossaryAdd ΓòÉΓòÉΓòÉ

This function adds the currently selected text to the current glossary file. It
is the equivalent to choosing Edit Mark Text Glossary.


Syntax
GlossaryAdd(Item, FileName, Flag)
Item is the glossary item name to insert into the glossary data file.
FileName is the name of the glossary file in which to insert the new item.
Flag is a number that defines whether the Filename parameter is a file name.
    FALSE (0) - Filename parameter is a file name
    TRUE (1) - Filename parameter is an object name

To display the Mark Glossary dialog box and allow the user to select the item
name and glossary data file: GlossaryAdd

Return Value
1  (TRUE) if the glossary record was inserted.
0  (NoAction) if no action was taken.
-2  (GeneralFailure) if the glossary record could not be inserted, if the data
file is not an Ami Pro file, or if the data file is encrypted.

Example
FUNCTION Example()
WHILE "" = CurShade$()
    UserControl("Select the text to place in the glossary, then choose
 Resume...")
WEND
GlossaryAdd
END FUNCTION

See also:

    GlossaryClose
    GlossaryLookup
    Glossary
    GlossaryOpen
    GlossSet



ΓòÉΓòÉΓòÉ 213. GlossaryClose ΓòÉΓòÉΓòÉ

This function closes a glossary data file.


You must use GlossaryClose after you use GlossaryOpen.

Syntax
GlossaryClose(handle)
Handle is the value returned by GlossaryOpen.

Return Value

Example
Function Gloss()
docpath = GetDocPath$()
h = GlossaryOpen("{docpath}glossary.sam")
if h
    record = GlossaryLookup(h, "id")
    message(id)
    GlossaryClose(h)
endif
end function

See also:

    GlossaryAdd
    GlossaryLookup
    Glossary
    GlossaryOpen
    GlossSet


ΓòÉΓòÉΓòÉ 214. GlossaryLookup ΓòÉΓòÉΓòÉ

This function looks up a record in a glossary data file.


You must use GlossaryOpen to open the data file before you can use
GlossaryLookup to locate a record in a glossary data file.

Syntax
GlossaryLookup(Handle, Keyword)
Handle is the value returned by GlossaryOpen.
Keyword is the ID of the record in the glossary data file you want to lookup.

Return Value
The record in the glossary data file. This is limited to one paragraph or 500
characters, whichever comes first.
If the Keyword is not found, the null string is returned.

Example
Function Gloss()
docpath = GetDocPath$()
h = GlossaryOpen("{docpath}glossary.sam")
if h
    record = GlossaryLookup(h, "id")
    message(id)
    GlossaryClose(h)
endif
end function

See also:

    GlossaryAdd
    GlossaryClose
    GlossaryLookup
    Glossary
    GlossaryOpen
    GlossSet



ΓòÉΓòÉΓòÉ 215. GlossaryOpen ΓòÉΓòÉΓòÉ

This function opens a glossary data file. Once the glossary file is open, you
can retrieve a record from the file.


You must use GlossaryClose after you use GlossaryOpen.

Syntax
GlossaryOpen("{path}FileName")
Path is the location of the glossary data file.
FileName is the name of glossary data file you want to open.

Return Value
Handle of glossary file, if the file is found.
0 if the file is not found.

Example
Function Gloss()
docpath = GetDocPath$()
h = GlossaryOpen("{docpath}glossary.sam")
if h
    record = GlossaryLookup(h, "id")
    message(id)
    GlossaryClose(h)
endif
end function

See also:

    GlossaryAdd
    GlossaryClose
    GlossaryLookup
    Glossary
    GlossaryOpen
    GlossSet


ΓòÉΓòÉΓòÉ 216. GlossSet ΓòÉΓòÉΓòÉ

This function selects the named glossary file to use as the source file for
insertion of glossary items. This function is equivalent to choosing Edit
Insert Glossary Record and choosing Data File.


Syntax
GlossSet(FileName)
FileName is the name of the glossary file from which to select records.

To display the Glossary dialog box and allow the user to select the name of the
glossary file: Glossary

Return Value
1  (TRUE) if a glossary file was selected.
-2  (GeneralFailure) if the file could not be selected or if the file was not
found.

Example
FUNCTION Example()
Gloss = Query$("What glossary file do you want to use?")
GlossSet(Gloss)
Glossary
END FUNCTION

See also:

    GlossaryAdd
    GlossaryClose
    GlossaryLookup
    Glossary
    GlossaryOpen


ΓòÉΓòÉΓòÉ 217. GoToAgain ΓòÉΓòÉΓòÉ

This function goes to the next location of an item after using the GoToCmd
function. This function is equivalent to choosing Edit Go To and selecting OK.


Syntax
GoToAgain()

Return Value
1  (TRUE) if the item was located.
0  (UserCancel) if the user canceled the function.
-3  if the input was invalid.
-7  if the item to Go To could not be found.
-2  if any other error.

Example
FUNCTION Example()
WHILE not AtEOF()
    GoToCmd(4, 0, GoField)
    TYPE("[DEL]")
WEND
END FUNCTION

See also:

    GoToCmd


ΓòÉΓòÉΓòÉ 218. GoToCmd ΓòÉΓòÉΓòÉ

This function allows the user to go to a page or a mark. This function is
equivalent to choosing Edit Go To.


Syntax
GoToCmd(Which, Page, Name)
Which is a flag that determines what type of object to Go To, and can be one of
the following:
    GoPage (1) - Goes to the page number specified in the Page  Parameter.
    GoFirst (2) - Goes to the first page of the document.
    GoLast (3) - Goes to the last page of the document.
    GoMark (4) - Goes to the mark specified in the MarkName parameter.
To go to a specific page, set the Which parameter to 1, set the Page parameter
to the page number you want to go to, and set the MarkName parameter to 0.
Parameters not necessary for a specific function may be set to 0. However,
Keystroke Record may use other numbers. These numbers are ignored, but must be
present.
To go to the first or last page, set the Which parameter to either 2 or 3, and
set the Page parameter and the MarkName parameter to 0.
To go to a mark, set the Which parameter to 4, set the Page parameter to 0, and
set the MarkName parameter to the value for the mark you want to go to.
Page is the page number to go to if you want to go to a page number.
Name is the type of mark to go to if you want to go to a mark. It can be one of
the following:
    GoFrame (1) - Go to the next frame
    GoHeader (2) - Go to the header area
    GoFooter (3) - Go to the footer area
    GoField (4) - Go to the next field
    GoTab (5) - Go to the tab ruler
    GoRuler (6) - Go to the next tab ruler mark in the text
    GoFootnote (7) - Go to the next footnote mark
    GoFoottext (8) - Go to the text of the footnote
    GoPageBreak (9) - Go to the next hard page break
    GoNote (10) - Go to the next note
    GoLayout (11) - Go to the next layout change
    GoBookmark (12) - Go to the next Bookmark
    GoHF (13) - Go to the next floating Header/Footer mark

To display the Go To dialog box and allow the user to select the parameters for
the Go To function: GoToCmd

Return Value
1  (TRUE) if the desired location was reached.
0  (UserCancel) if the user canceled the function.
-3  if the desired mark could not be found (for example, going to a frame in
Draft Mode).
-7  if the desired location could not be found.
-2  if any other error.

Example
FUNCTION Example()
WHILE not AtEOF()
    GoToCmd(4, 0, GoField)
    TYPE("[DEL]")
WEND
END FUNCTION

See also:

    GetMarkText$
    Replace
    GoToAgain


ΓòÉΓòÉΓòÉ 219. GoToPowerField ΓòÉΓòÉΓòÉ

This function moves the insertion point to a specific power field.


Syntax
GoToPowerField(ID, 0)
ID is the number assigned to a specific power field. You can obtain the ID by
using GetPowerFields.

Return Value
1 (TRUE) if the power field is located.
0 (FALSE) if the power field is not located.

Example
FUNCTION Example()
Count = GetPowerFieldCount(9)  ' Get the User powerfields
If count <1
    Message("No powerfields are in this document.")
    Exit Function       ' No powerfields, Exit macro
Endif
DIM Power(Count)
GetPowerFields(0, &Power)
FOR i = 1 to Count
    pfid = strfield$(Power(i), 1, ",")
    pftype = strfield$(Power(i), 2, ",")
    pageno = GetPowerFieldPage(pfid, pftype)
NEXT
GoToPowerField(pfid, pftype)
END FUNCTION

See also:

    GetPowerFieldCount
    GetPowerFieldPage
    GetPowerFields


ΓòÉΓòÉΓòÉ 220. GrayMenuItem ΓòÉΓòÉΓòÉ

This function grays or ungrays a menu item. When a menu item is grayed, it
appears on the menu, but the user cannot select it. Use this function to
indicate that the function is currently unavailable.


Syntax
GrayMenuItem(BarID, MenuName, Item, State)
BarID is the identification number of the menu bar and must always be 1.
MenuName is the name of the menu where the item to be grayed is located. The
name must include any ampersand (&) characters used in the menu name. An
ampersand is placed before a character that has an underline.
Item is the name of the menu item to be grayed, and must match the actual menu
item, including any ampersand (&) characters. If the menu item has a shortcut
key, you must press TAB, type a ^, and then type the appropriate letter as part
of the item name.
State is either 1 (TRUE) to gray the menu item, or 0 (FALSE) to ungray the menu
item.

Return Value
1  (TRUE) if the item was successfully grayed or ungrayed.
0  (FALSE) if the item could not be grayed/ungrayed, or if an invalid BarID,
MenuName, or ItemName was used.

Example
FUNCTION Example()
' This example might be used if you wanted to prevent users from applying
special
' effects attributes to text of a file that may be exported to another format
GrayMenuItem(1, "&Text", "Special &Effects...", 1) ' gray the menu item
OnCancel RestoreIt ' in case the user cancels
' pause the macro
UserControl("Inspect the ""Text"" menu then select Resume")
RestoreIt:
GrayMenuItem(1, "&Text", "Special &Effects...", 0) ' ungray the menu item
END FUNCTION

See also:

    AddMenu
    AddMenuItem
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    DeleteMenuItem
    RenameMenuItem


ΓòÉΓòÉΓòÉ 221. HeaderFooter ΓòÉΓòÉΓòÉ

This function goes to the header or footer or displays the Floating Header
Footer dialog box. This function is equivalent to choosing Page Header Footer.


Syntax
HeaderFooter(Function)
Function is a flag that can be one of the following:
    (1) - Go to the header
    (2) - Go to the footer
    (3) - Display Floating Header/Footer dialog box

To display the Headers & Footers dialog box: HeaderFooter

Return Value
This function returns:
0  (UserCancel) if the user cancels the function.
1  (TRUE) if the header or footer is found or the Floating Header/Footer dialog
box displays.
-6  (NoMemory) if the function fails because of insufficient memory.

Example
FUNCTION Example()
HeaderFooter(1)  ' Go to the header
Type("This is a test.")
END FUNCTION

See also:

    GoToCmd
    ModifyLayout
    PageNumber


ΓòÉΓòÉΓòÉ 222. Help ΓòÉΓòÉΓòÉ

This function displays the online Help for Ami Pro. This function is equivalent
to choosing Help Contents, but it does not select a Help topic automatically.
Because Help displays in a window other than the regular Ami Pro window,
further macro functions which cause a repainting of the Ami Pro window cause
the Help window to be replaced by the Ami Pro window.


If this function is used, it should be the last function used in the macro.

Syntax
Help()

Return Value
This  Function Returns:
1  (TRUE) if the Help window was displayed.
-2  (GeneralFailure) if the Help window could not be displayed for some other
reason.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
Help()
END FUNCTION

See also:

    About
    HowDoIHelp
    MacroHelp
    UsingHelp


ΓòÉΓòÉΓòÉ 223. HideIconBar ΓòÉΓòÉΓòÉ

This function hides the set of SmartIcons. This function is equivalent to
choosing View Hide SmartIcons.


Syntax
HideIconBar()

Return Value
1  (TRUE) if the icon bar was hidden.
0  (NoAction) if no action was taken because the icon bar was already hidden.

Example
FUNCTION Example()
ReturnValue = HideIconBar()
IF ReturnValue != 1
    IF Decide("Icon bar already hidden! Would you like it displayed?")
       ShowIconBar()
    ENDIF
ENDIF
END FUNCTION

See also:

    ChangeIcons
    GetIconPalette
    IconCustomize
    SetIconPath
    SetIconSize
    ShowIconBar
    ToggleIconBar
    ViewPreferences


ΓòÉΓòÉΓòÉ 224. HideTabRuler ΓòÉΓòÉΓòÉ

This function removes the tab ruler from the top of the screen. This function
is equivalent to choosing View Hide Ruler.


Syntax
HideTabRuler()

Return Value
1  (TRUE) if the tab ruler was hidden.
0  (NoAction) if no action was taken because the tab ruler was already hidden.

Example
FUNCTION Example()
HideTabRuler()
END FUNCTION

See also:

    ShowTabRuler
    ToggleTabRuler
    ViewPreferences


ΓòÉΓòÉΓòÉ 225. HourGlass ΓòÉΓòÉΓòÉ

This function turns on or off the OS/2 clock mouse pointer. The original state
of the clock can be determined from the function's return value. If a macro
changes the state of the clock mouse pointer, it must restore the original
state before exiting. If it does not restore the mouse pointer, the insertion
point is incorrect from that point on.


Syntax
HourGlass(State)
State is either On (1) to turn on the clock mouse pointer or Off (0) to turn it
off.

Return Value
1  (TRUE) if the clock was on prior to using the clock function.
0  (FALSE) if the clock was off.

Example
FUNCTION Example()
IgnoreKeyboard(1)
HourGlass(1)
StatusBarMsg("Importing graphic file...")
ImportPicture("Bitmap", "C:\AMIPRO\ICONS\123W.BMP", ".BMP", 0)
StatusBarMsg("")
HourGlass(0)
IgnoreKeyboard(0)
END FUNCTION

See also:

    AnswerMsgBox
    Messages
    Pause
    SingleStep
    StatusBarMsg



ΓòÉΓòÉΓòÉ 226. HowDoIHelp ΓòÉΓòÉΓòÉ

This function displays the online Help for Ami Pro. This function is equivalent
to choosing Help How Do I?, but it does not select a Help topic automatically.
Because Help displays in a window other than the regular Ami Pro window,
further macro functions which cause a repainting of the Ami Pro window cause
the Help window to be replaced by the Ami Pro window.


If this function is used, it should be the last function used in the macro.

Syntax
HowDoIHelp()

Return Value
1  (TRUE) if the Help window was displayed.
-2  (GeneralFailure) if the Help window could not be displayed for some other
reason.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
HowDoIHelp()
END FUNCTION

See also:

    About
    Help
    MacroHelp
    UsingHelp


ΓòÉΓòÉΓòÉ 227. ICONBOTTOM ΓòÉΓòÉΓòÉ

This function moves the set of SmartIcons to the bottom of the screen. This
function is equivalent to choosing Tools SmartIcons and selecting Bottom for
the position.


A macro must be edited to insert this non-recordable function.

Syntax
IconBottom()

Return Value
This function returns 1.

Example
FUNCTION Example()
IconBottom()
END FUNCTION

See also:

    HideIconBar
    IconCustomize
    IconFloating
    IconLeft
    IconRight
    IconTop
    SetIconSize
    ShowIconBar
    ToggleIconBar


ΓòÉΓòÉΓòÉ 228. IconCustomize ΓòÉΓòÉΓòÉ

This function displays the SmartIcons dialog box that allows the user to
customize the Smarticons set. This function is equivalent to choosing Tools
SmartIcons.


A macro must be edited to insert this non-recordable function.

Syntax
IconCustomize()

Return Value
1  (TRUE) if the SmartIcons were customized.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
IconCustomize()
END FUNCTION

See also:

    ChangeIcons
    HideIconBar
    IconBottom
    IconFloating
    IconLeft
    IconRight
    IconTop
    SetIconPath
    SetIconSize
    ShowIconBar
    ToggleIconBar



ΓòÉΓòÉΓòÉ 229. IconFloating ΓòÉΓòÉΓòÉ

This function moves the set of SmartIcons to a floating position on the screen.
This function is equivalent to choosing Tools SmartIcons and selecting Floating
for the position.


A macro must be edited to insert this non-recordable function.

Syntax
IconFloating()

Return Value
This function returns 1.

Example
FUNCTION Example()
IconFloating()
END FUNCTION

See also:

    HideIconBar
    IconBottom
    IconCustomize
    IconLeft
    IconRight
    IconTop
    SetIconSize
    ShowIconBar
    ToggleIconBar



ΓòÉΓòÉΓòÉ 230. IconLeft ΓòÉΓòÉΓòÉ

This function moves the set of SmartIcons to the left side of the screen. This
function is equivalent to choosing Tools SmartIcons and selecting Left for the
position.


A macro must be edited to insert this non-recordable function.

Syntax
IconLeft()

Return Value
This function returns 1.

Example
FUNCTION Example()
IconLeft()
END FUNCTION

See also:

    HideIconBar
    IconBottom
    IconCustomize
    IconFloating
    IconRight
    IconTop
    SetIconSize
    ShowIconBar
    ToggleIconBar



ΓòÉΓòÉΓòÉ 231. IconRight ΓòÉΓòÉΓòÉ

This function moves the set of SmartIcons to the right side of the screen. This
function is equivalent to choosing Tools SmartIcons and selecting Right for the
position.


A macro must be edited to insert this non-recordable function.

Syntax
IconRight()

Return Value
This function returns 1.

Example
FUNCTION Example()
IconRight()
END FUNCTION

See also:

    HideIconBar
    IconBottom
    IconCustomize
    IconFloating
    IconLeft
    IconTop
    SetIconSize
    ShowIconBar
    ToggleIconBar


ΓòÉΓòÉΓòÉ 232. IconTop ΓòÉΓòÉΓòÉ

This function moves the set of SmartIcons to the top of the screen. This
function is equivalent to choosing Tools SmartIcons and selecting Top for the
position.


A macro must be edited to insert this non-recordable function.

Syntax
IconTop()

Return Value
This function returns 1.

Example
FUNCTION Example()
IconTop()
END FUNCTION

See also:

    HideIconBar
    IconBottom
    IconCustomize
    IconFloating
    IconLeft
    IconRight
    SetIconSize
    ShowIconBar
    ToggleIconBar


ΓòÉΓòÉΓòÉ 233. ImageProcessing ΓòÉΓòÉΓòÉ

This function adds the Image menu to the main menu bar. This function is
equivalent to choosing Tools Image Processing.


A frame containing a gray scale TIFF image must be selected before calling this
function.

Syntax
ImageProcessing()

Return Value
1  (TRUE) if the Image menu was added to the main menu bar.
-2  (GeneralFailure) if the Image menu could not be added.

Example
FUNCTION Example()
LayoutMode()
WHILE not IsFrameSelected()
    UserControl("Select a frame with a gray scale tiff and choose Resume...")
WEND
ImageProcessing()
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    FrameLayout
    ManualFrame


ΓòÉΓòÉΓòÉ 234. ImportExport ΓòÉΓòÉΓòÉ

This function allows you to import a non-Ami Pro file or export a file to
another file format. If you are importing a file, the macro should make sure
the insertion point is at the location in the file where the new file should be
imported. If exporting a file, the file to be exported should be on the screen.


Syntax
ImportExport(Which, FileName, FilterName, CopyImage)
Which indicates if the file should be imported or exported. The Which parameter
should be set according to the list below:
    Export (1) - Exports the file onscreen to a new file
    Import (0) - Imports the specified file to the current document
FileName is the full path of the file being imported or the destination path of
the file to export to.
FilterName is the name of the filter as listed in the Open dialog box or in
amipro3.ini.
CopyImage is a flag indicating whether to copy the graphic file or use the
information in the original graphics file. The CopyImage parameter should be
set to 1 (True) if the graphic file should be copied into the document. It
should be set to 0 (False) if the original graphic file should be referred to
when the graphic is displayed.
ASCII
IMPORT and EXPORT syntax:
ImportExport(Which, FileName, FilterName, CopyImage, CRLF, Type, KeepStyle)
CRLF - Carriage return/linefeed options
    LINE - Use carriage return/linefeed characters at end of line
    PARA - Use carriage return/linefeed characters at end of paragraph
Type - is the type of ASCII file to import or export
    PCASCII (8) - 8 bit PC ASCII file
    ANSI (16) - 8 bit ANSI file
KeepStyle allows you to keep the style names
    KeepStyle - Keep style names

DisplayWrite 4
EXPORT Syntax:
ImportExport(Which, FileName, FilterName, CopyImage, StyleBox)
StyleBox - Choices for the Styles box
    Apply - Apply styles
    Ignore (5) - Ignore styles

DCA/RFT
EXPORT Syntax:
ImportExport(Which, FileName, FilterName, CopyImage, StyleBox)
StyleBox - Choices for the Styles box
    Apply - Apply styles
    Ignore (5)  - Ignore styles

Lotus 1-2-3 Version 3.0 and higher
IMPORT Syntax:
ImportExport(Which, FileName, FilterName, CopyImage, RangeBox[, Range],
StyleBox)
RangeBox - Choices for the Range box
    Entire - Entire file
    Active - Active worksheet
    Range - Range. This parameter must be followed by another giving the exact
    range.
Range - Range if the RangeBox parameter has a range
StyleBox - Choices for the Styles box
    Convert - Convert styles
    Apply - Apply styles
    Keep - Keep style names
    Ignore (5) - Ignore styles

Rich Text Format, Word for Windows 1.x and 2.0
IMPORT Syntax:
ImportExport(Which, FileName, FilterName, CopyImage, StyleBox)
StyleBox - Choices for the Styles box
    Convert - Convert styles
    Apply - Apply styles
    Keep - Keep style names
    Ignore (5) - Ignore styles

WordPerfect 5.0 and 5.1
IMPORT Syntax:
ImportExport(Which, FileName, FilterName, CopyImage, StyleBox)
StyleBox - Choices for the Styles box
    Apply - Apply styles
    Ignore (5) - Ignore styles
    Style - Import style sheet
EXPORT Syntax:
ImportExport(Which, FileName, FilterName, CopyImage, StyleBox, Version)
StyleBox - Choices for the Styles box
    Convert - Convert styles
    Apply - Apply styles
    Ignore (5) - Ignore styles
Version is the version of WordPerfect
    TRUE (1) - Wordperfect 5.0 format
    FALSE (0) - Wordperfect 5.1 format
For all exports: If the export file already exists, a message box prompts you
whether or not to overwrite the existing file.
This function does not display a dialog box.

Return Value
1  (TRUE) if the file was successfully imported/exported.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the file could not be imported because the file was not
the appropriate type or if the file could not be found.

Example
FUNCTION Example()
ImportExport(Import, "C:\AUTOEXEC.BAT", "ASCII", 0, "PARA", PCASCII, 0)
END FUNCTION

See also:

    ASCIIOptions
    FileOpen
    ImportPicture
    SaveAs


ΓòÉΓòÉΓòÉ 235. ImportPicture ΓòÉΓòÉΓòÉ

This function imports a graphic into the current document. If an empty frame is
selected, the graphic is placed in it. If no frame is selected, this function
creates a 1" by 1" frame and imports the graphic into it. This function is
equivalent to choosing File Import Picture.


Syntax
ImportPicture(App, FileName, FileExt, CopyImage)
App is the name of the application filter name. This name may be extracted from
the list of file types in the Import Picture dialog box. The name may also be
found in the amipro3.ini file.
FileName is the name of the file and extension to be imported and the full
path, if necessary.
FileExt is the extension of the file to be imported. There must be a period (.)
before the extension name.
CopyImage can be one of the following values:
    (1) - Graphics file copied into the document.
    (0) - Original graphics file referred to when the graphic is displayed.

Return Value
1  (TRUE) if the picture was imported.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the picture was not imported.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
IgnoreKeyboard(1)
HourGlass(1)
StatusBarMsg("Importing graphic file...")
ImportPicture("Bitmap", "C:\AMIPRO\ICONS\123W.BMP", ".BMP", 0)
StatusBarMsg("")
HourGlass(0)
IgnoreKeyboard(0)
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    FileOpen
    GetProfileString$
    HourGlass
    ImageProcessing
    ImportExport




ΓòÉΓòÉΓòÉ 236. Indent ΓòÉΓòÉΓòÉ

This function sets the amount of indention for the current paragraph. This
function is equivalent to choosing  text Indention.


Syntax
Indent(AllIndent, FirstIndent, RestIndent, RightIndent)
AllIndent is the amount to indent all the lines.
FirstIndent is the amount to indent the first line.
RestIndent is the amount to indent the rest of the lines after the first line.
RightIndent is the amount to indent from the right side.
All amounts are in twips (1 inch = 1440 twips). Multiply the desired number of
inches by 1440 to determine the value in twips.

To display the Indention dialog box: Indent

Return Value
1  (TRUE) if the indention was set.
0  (UserCancel) if the user canceled the function.
-6  (InsufficientMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' indent all lines 1 inch and the first line another half inch
Indent(1440, 720, 0, 0)
END FUNCTION

See also:

    Center
    FastFormat
    IndentAll
    IndentFirst
    IndentRest
    Justify
    LeftAlign
    NormalText
    RightAlign
    Spacing


ΓòÉΓòÉΓòÉ 237. IndentAll ΓòÉΓòÉΓòÉ

This function allows you to increase the amount of indention for the selected
text. This function is equivalent to clicking the Indent All icon. The amount
of indention to be increased is determined by the value set in Text Indention
Indent All. If the units in User Setup is set to centimeters, the amount to
increase is 1 centimeter. For the other units (inches, picas, or points), the
amount to increase is one half of an inch.


Syntax
IndentAll()

Return Value
1  (TRUE) if the indention was increased.
-6  (InsufficientMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' indent the selected text to the specified indention
IndentAll()
END FUNCTION

See also:

    IndentFirst
    Indent
    IndentRest


ΓòÉΓòÉΓòÉ 238. IndentFirst ΓòÉΓòÉΓòÉ

This function allows you to increase the amount of indention for the selected
text. This function is equivalent to clicking the Indent First icon. The amount
of indention to be increased is determined by the value set in Text Indention
Indent First. If the units in User Setup is set to centimeters, the amount to
increase is 1 centimeter. For the other units (inches, picas, or points), the
amount to increase is one half of an inch.


Syntax
IndentFirst()

Return Value
1  (TRUE) if the indention was increased.
-6  (InsufficientMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' indent the first line to the specified indention
IndentFirst()
END FUNCTION

See also:

    IndentAll
    Indent
    IndentRest


ΓòÉΓòÉΓòÉ 239. IndentRest ΓòÉΓòÉΓòÉ

This function allows you to increase the amount of indention for the selected
text. This function is equivalent to clicking the Indent Rest icon. The amount
of indention to be increased is determined by the value set in Text Indention
Indent Rest. If the units in User Setup is set to centimeters, the amount to
increase is 1 centimeter. For the other units (inches, picas, or points), the
amount to increase is one half of an inch.


Syntax
IndentRest()

Return Value
1  (TRUE) if the indention was increased.
-6  (InsufficientMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' indent the rest of the lines to the specified indention
IndentRest()
END FUNCTION

See also:

    IndentAll
    IndentFirst
    Indent


ΓòÉΓòÉΓòÉ 240. InsertBullet ΓòÉΓòÉΓòÉ

This function inserts a bullet into the text at the cursor position. This
function is equivalent to choosing Edit Insert Bullet.


Syntax
InsertBullet(Type)
Type is the type of bullet to insert and can be one of the following:
    (1) - Small round bullet
    (2) - Large round bullet
    (3) - Small square bullet
    (4) - Large square bullet
    (5) - Large outline square bullet
    (6) - Small diamond bullet
    (7) - Large diamond bullet
    (8) - Small open circle bullet
    (9) - Large open circle bullet
    (10) - Check mark
    (11) - Tack
    (12) - Square shadow below bullet
    (13) - Square shadow above bullet
    (14) - Check box
    (15) - Square with X bullet
    (16) - Rounded arrowhead top shaded
    (17) - Rounded arrowhead bottom shaded

To display the Insert Bullet dialog box to allow the user to select a bullet:
InsertBullet

Return Value
1 (TRUE) if the bullet is inserted.
-2 (GeneralFailure) is the insertion failed.

Example
FUNCTION Example()
' type every kind of bullet
FOR type = 1 to 17
    InsertBullet(type)
    type("[Enter]")
NEXT
END FUNCTION

See also:

    InsertDate
    InsertDocInfo
    ModifyEffects
    ModifyStyle


ΓòÉΓòÉΓòÉ 241. InsertCascadeMenu ΓòÉΓòÉΓòÉ

This function inserts a cascade menu in an existing pull down menu.


Syntax
InsertCascadeMenu(BarID, Menu, Position, NewMenu)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu to insert this cascade menu on. This
string must contain any ampersand (&) characters used in the menu name. An
ampersand is placed before a character that has an underline.
Position is the position in the pull down menu to insert the cascade menu. This
parameter begins with 0 (to insert as the first position in the pull down
menu).
NewMenu is the name of the cascade menu to insert. Placing an ampersand (&)
character in front of a character in the string makes that string appear
underlined and causes that character to become a shortcut character.

Return Value
1  (TRUE) if the cascade menu was inserted.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the cascade menu could not be inserted or if the pull
down menu name does not match or exist.

Example
FUNCTION Example()
' get the name of this macro file
MacFile = GetRunningMacroFile$()
InsertCascadeMenu(1, "&File", 7, "&Example")
AddCascadeMenuItem(1, "&File", "&Example", "Example1", "{MacFile}!Example2(1)",
"")
AddCascadeMenuItem(1, "&File", "&Example", "Example2", "{MacFile}!Example2(2)",
"")
InsertCascadeMenuItem(1, "&File", "&Example", 1, "Example1.5", "
{MacFile}!Example2(3)", "")
END FUNCTION

FUNCTION Example2(Msg)
Message(Msg)
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    ChangeCascadeAction
    DeleteMenu
    DeleteMenuItem
    InsertCascadeMenuItem
    InsertMenuItem
    InsertMenu


ΓòÉΓòÉΓòÉ 242. InsertCascadeMenuItem ΓòÉΓòÉΓòÉ

This function inserts a cascade menu item on an existing cascade menu.


Syntax
InsertCascadeMenuItem(BarID, Menu, Position, Item, MacroName[!Function[(parm1[,
parm2...])]], Help)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the cascade menu this item should be inserted in. This must
match exactly the name of the menu item you want to use, including any
ampersand (&) characters in the name of the menu. An ampersand is placed before
a character that has an underline.
Position is where to locate the item in the cascade menu.
This parameter begins with 0 (to insert as the first position in the cascade
menu).
Item is the text to insert. This is the text that the user sees on the cascade
menu bar. Placing an ampersand (&) in front of a character causes that
character to appear underlined and makes that character a shortcut key. If the
menu item has a shortcut key, you must press TAB, type a ^, and then type the
appropriate letter as part of the item name.
MacroName is the name of the macro to run if this menu item is selected. This
parameter may contain the macro filename, the function within that file to
call, and any parameters that the function may require. At a minimum, this
parameter must contain the macro filename.
Help is the one-line Help text that appears in the title bar of Ami Pro when
this menu item is highlighted. This parameter is not optional for this
function.

Return Value
1  (TRUE) if the cascade menu item was inserted.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the cascade menu item could not be inserted, or if the
pull down menu or the cascade menu names did not match the parameters or if
either did not exist.

Example
FUNCTION Example()
' get the name of this macro file
MacFile = GetRunningMacroFile$()
InsertCascadeMenu(1, "&File", 7, "&Example")
AddCascadeMenuItem(1, "&File", "&Example", "Example1", "{MacFile}!Example2(1)",
"")
AddCascadeMenuItem(1, "&File", "&Example", "Example2", "{MacFile}!Example2(2)",
"")
InsertCascadeMenuItem(1, "&File", "&Example", 1, "Example1.5", "
{MacFile}!Example2(3)", "")
END FUNCTION

FUNCTION Example2(Msg)
Message(Msg)
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    ChangeCascadeAction
    DeleteMenu
    DeleteMenuItem
    InsertCascadeMenu
    InsertMenuItem
    InsertMenu


ΓòÉΓòÉΓòÉ 243. InsertColumnRow ΓòÉΓòÉΓòÉ

This function inserts table columns or rows. This function is equivalent to
choosing Table Insert Column Row.


Syntax
InsertColumnRow(Number, Where, Which)
Number is the number of columns or rows to insert.
Where is a number representing where to insert the columns or rows and can be
one of the following:
    InsAfter (0) - Inserts after the current column/row
    InsBefore (1) - Inserts before the current column/row
Which is a number determining whether to insert columns or rows and can be one
of the following:
    Column (1) - Inserts a column
    Row (0) - Inserts a row

To display the Insert Column Row dialog box to allow the user to decide the
number and type of columns/rows to insert: InsertColumnRow

Return Value
1  (TRUE) if the column or row was inserted.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the row or column was not inserted.

Example
FUNCTION Example()
' Insert 1 column after the current column
InsertColumnRow(1, 0, 1)
END FUNCTION

See also:

    DeleteColumnRow
    DeleteEntireTable
    SelectColumn
    SelectEntireTable
    SelectRow
    SizeColumnRow


ΓòÉΓòÉΓòÉ 244. InsertDate ΓòÉΓòÉΓòÉ

This function inserts a date into the document. This function is equivalent to
choosing Edit Insert Date/Time.


Syntax
InsertDate(Type, Style)
Type is the type of date to insert and can be one of the following:
    Today (2) - Inserts the current system date and always displays this date
    SysDate (3) - Inserts the current system date and updates this date each
    time you open the document
    LastRev (5) - Inserts the date the document was last revised
    CreateDate (7) - Inserts the date the document was created
Style is the style of date to insert and can be one of the following:
    (0) NMDY - 9/11/91
    (1) MDY - September 11, 1991
    (2) UMDY - SEPTEMBER 11, 1991
    (3) DMY - 11 September 1991
    (4) UDMY - 11 SEPTEMBER 1991
    (5) DMDY - Friday, September 11, 1991
    (6) UDMDY - FRIDAY, SEPTEMBER 11, 1991
    (7) MD - September 11
    (8) UMD - SEPTEMBER 11
    (9) DMD - Friday September 11
    (10) UDMD - FRIDAY SEPTEMBER 11
    (11) NMD - 9/11
    (12) NMDLY - 9/11/91
    (13) DPM - 11. September
    (14) UDPM - 11. SEPTEMBER
    (15) DPMY - 11. September 1991
    (16) UDPMY - 11. SEPTEMBER 1991
    (17) YMD - 1991 September 11
    (18) UYMD - 1991 SEPTEMBER 11
    (19) MY - September, 1991
    (20) UMY - SEPTEMBER, 1991

To display the Insert Date Time dialog box and allow the user to select the
date type and style: InsertVariable

Return Value
1  (TRUE) if the date was inserted.
-2  (GeneralFailure) if no date was inserted.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
InsertDate(2, DMDY)
END FUNCTION

See also:

    FormatDate$
    FormatTime$
    GetTime
    InsertBullet
    InsertDocInfo
    InsertVariable
    Now



ΓòÉΓòÉΓòÉ 245. InsertDocInfo ΓòÉΓòÉΓòÉ

This function displays the Insert Doc Info dialog box. This function is
equivalent to choosing Edit Insert Doc Info Field.

To insert the Doc Info  field without the dialog box, use the
InsertDocInfoField function.

Syntax
InsertDocInfo

Return Value
This function does not return a value.

Example
FUNCTION Example()
InsertDocInfo
END FUNCTION

See also:

    DocInfo
    GetDocInfo$
    InsertDocInfoField
    RenameDocInfoField




ΓòÉΓòÉΓòÉ 246. InsertLayout ΓòÉΓòÉΓòÉ

This function inserts a page break at the current insertion point and displays
the Modify Page Layout dialog box. This function is equivalent to choosing Page
Insert Page Layout Insert.


You must be in Layout Mode to use this function.

Syntax
InsertLayout()

Return Value
This function returns 1.

Example
FUNCTION Example()
InsertLayout()
END FUNCTION

See also:

    CreateStyle
    HeaderFooter
    ModifyLayout
    ModifyStyle
    RemoveLayout


ΓòÉΓòÉΓòÉ 247. InsertMenu ΓòÉΓòÉΓòÉ

This function inserts a new pull down menu on the specified menu bar.


Syntax
InsertMenu(BarID, Position, NewMenu)
BarID is the identification number of the menu bar and must always be 1..
Position is where to locate the menu.
This parameter begins with 0 (to insert as the first position on the menu bar).
NewMenu is the name of the new menu name to insert. Placing an ampersand (&) in
front of a character causes that character to appear underlined and makes that
character a shortcut key.

Return Value
1  (TRUE) if the menu was inserted.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the menu could not be inserted.

Example
FUNCTION Example()
InsertMenu(1, 1, "&NewMenu")
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    DeleteMenu
    DeleteMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenuItem
    RenameMenuItem


ΓòÉΓòÉΓòÉ 248. InsertMenuItem ΓòÉΓòÉΓòÉ

This function inserts a new menu item on the specified pull down menu.


Syntax
InsertMenuItem(BarID, Menu, Position, Item, MacroName[!Function[(parm1[,
parm2...])]][, Help])
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the existing menu to insert this item in. The exact name of
the menu must be used, including any ampersand (&) characters. An ampersand is
placed before a character that has an underline.
Position is where to locate the menu item in the pull down menu.
This parameter begins with 0 (to insert as the first position in the pull down
menu).
Item is the text to appear for this menu item. Placing an ampersand (&) in
front of a character causes that character to appear underlined and makes that
character a shortcut key. If the menu item has a shortcut key, you must press
TAB, type a ^, and then type the appropriate letter as part of the item name.
MacroName is the name of the macro to run if this menu item is selected. This
parameter may contain the macro filename, the function within that file to
call, and any parameters that function may require. At a minimum, this
parameter must contain the macro filename.
Help is the one-line Help text that appears in the title bar of Ami Pro when
this menu item is highlighted.

Return Value
1  (TRUE) if the menu item was inserted.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the menu item could not be inserted.

Example
FUNCTION Example()
' get the name of this macro file
MacFile = GetRunningMacroFile$()
State = 0
DeleteMenuItem(1, "&Text", "B&old+Italic+Underline")
InsertMenuItem(1, "&Text", 10, "B&old+Italic+Underline", "{MacFile}!Example2(
{State})", "Bold and Italicize and Underline Text.")
END FUNCTION

FUNCTION Example2(State)
MacFile = GetRunningMacroFile$()
State = Right$((State - 1), 1)
Bold(State)
Underline(State)
Italic(State)
ChangeMenuAction(1, "&Text", "B&old+Italic+Underline", "{MacFile}!Example2(
{State})", "Bold and Italicize and Underline Text.")
CheckMenuItem(1, "&Text", "B&old+Italic+Underline", State)
END FUNCTION

See also:

    AddCascadeMenu
    AddCascadeMenuItem
    AddMenu
    AddMenuItem
    DeleteMenu
    DeleteMenuItem
    InsertCascadeMenuItem
    InsertCascadeMenu
    InsertMenu
    RenameMenuItem


ΓòÉΓòÉΓòÉ 249. InsertMerge ΓòÉΓòÉΓòÉ

This function displays the Insert Merge Field dialog box. The user must select
the merge field to insert. This function is equivalent to choosing Edit Insert
Merge Field.

To insert the field automatically, use the FieldAdd function.

Syntax
InsertMerge

Return Value
This function returns 0.

Example
FUNCTION Example()
InsertMerge
END FUNCTION

See also:

    FieldAdd
    FieldRemove
    MergeAction
    Merge
    MergeMacro
    MergeToFile




ΓòÉΓòÉΓòÉ 250. InsertMergeField ΓòÉΓòÉΓòÉ

This function inserts a merge field into a standard document. It is equivalent
to choosing Edit Insert from the menu. This function inserts the field without
checking to make sure it is a valid field name.


Make sure field names that are inserted match with the data files that will be
used to merge.

Syntax
InsertMergeField(Field)
Field is the name of the merge field that must be inserted.

To display the Insert Merge Field dialog box and let the user select the field
name to insert: InsertMerge.

Return Value
1  (TRUE) if the field name was inserted.
-2  (GeneralFailure) if the field name was not inserted.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
InsertMergeField(Query$("What is the name of the merge field to insert?"))
END FUNCTION

See also:

    FieldAdd
    InsertDate
    InsertDocInfo
    InsertMerge
    InsertVariable


ΓòÉΓòÉΓòÉ 251. InsertNote ΓòÉΓòÉΓòÉ

This function inserts a note with the specified text at the insertion point.
The note is automatically inserted, and the note window is closed using this
function. This function is equivalent to choosing Edit Insert Note, typing the
note, and closing the note.

A macro must be edited to insert this non-recordable function.

Syntax
InsertNote(Text)
Text is the text that should go inside the note.
To allow the user to determine note options or to type the note text: Notes

Return Value
This function returns:
 1  (TRUE) if the note was inserted.
-2  (GeneralFailure) if the note was not inserted.

Example
FUNCTION Example()
InsertNote("Ami Pro is the easiest word processor to learn.")
END FUNCTION

See also:

    Notes
    UserSetup
    ViewPreferences


ΓòÉΓòÉΓòÉ 252. InsertVariable ΓòÉΓòÉΓòÉ

This function displays the Insert Date Time dialog box. This function is
equivalent to choosing Edit Insert Date Time. This function does not insert
variables automatically. Variables can be directly inserted using the
InsertDate, InsertDocInfoField, and FieldAdd functions.


Syntax
InsertVariable

Return Value
This function returns 0.

Example
FUNCTION Example()
InsertVariable
END FUNCTION

See also:

    FieldAdd
    InsertDate
    InsertDocInfo


ΓòÉΓòÉΓòÉ 253. Instr ΓòÉΓòÉΓòÉ

This function searches a text string for a pattern. The Instr function can tell
you whether a specific string is contained in another string.


Syntax
Instr(Offset, Text, Pattern)
Offset is the position in the string to begin searching.
Text is the string to search.
Pattern is the pattern to search for.

Return Value
The value of the offset of the beginning of the pattern, if it is found.
0  (FALSE) if the offset is not found.

Example
FUNCTION Example()
Name = UCASE$(Query$("What is your name?"))
FOR I = 65 to 90
    Ltr = CHR$(I)
    IF 0 != Instr(0, Name, Ltr)
       TYPE("The letter {Ltr} is in your name.[Enter]")
    ENDIF
NEXT
END FUNCTION

See also:

    CHR$
    Left$
    MID$
    Right$
    strcat$
    strchr
    strfield$


ΓòÉΓòÉΓòÉ 254. IsFrameSelected ΓòÉΓòÉΓòÉ

This function determines whether or not a frame is currently selected.


Syntax
IsFrameSelected()

Return Value
1  (TRUE) if the frame is currently selected.
0  (FALSE) if the frame is not currently selected.

Example
function Example()
result=IsFrameSelected()
message(result)
end function

See also:

    AddFrame
    AddFrameDLG
    BringFrameToFront
    FrameLayout
    ManualFrame
    SelectFrameByName


ΓòÉΓòÉΓòÉ 255. IsNumeric ΓòÉΓòÉΓòÉ

This function determines whether a string is suitable for numeric operations.


Syntax
IsNumeric(Text)
Text is the string which is to be evaluated.

Return Value
1  (TRUE) if the passed string is numeric.
0  (FALSE) if the passed string is not numeric.

Example
FUNCTION Example()
again:
Num1 = Query$("What is the first number?")
Num2 = Query$("What is the second number?")
IF (not IsNumeric(Num1)) OR (not IsNumeric(Num2))
    GoTo again
ENDIF
sum = Num1 + Num2
Message("The sum of {Num1} and {Num2} is {sum}.")
END FUNCTION

See also:

    FormatNum$
    Mod
    Round


ΓòÉΓòÉΓòÉ 256. Italic ΓòÉΓòÉΓòÉ

This function sets the italic attribute for selected text or for all following
text if no text is selected. It acts as a toggle, turning off the attribute if
it is currently on or turning on the attribute if it is currently off. This
function is equivalent to choosing Text Italic.


Syntax
Italic()

Return Value
0  if the italic attribute is toggled on and there are no attributes assigned
to the text.
4  if the italic attribute is toggled on and the bold attribute is already
assigned.
8  if the italic attribute is toggled off.
16  if the italic attribute is toggled on and the underline attribute is
already assigned.
32  if the italic attribute is toggled on and the word underline attribute is
already assigned.
-2  (GeneralFailure) if the attribute was not changed.
The returns values may be added together to identify the attributes that were
previously assigned.

Example
FUNCTION Example()
text = Query$("Enter some text:")
New("_default.sty", 0, 0)      'open a new file
TYPE("{text}")
TYPE("[enter]")
TYPE("[ctrlhome][ctrlshiftend]")
Copy() 'copy text to clipboard
FOR I = 1 to 10
    Paste()   'paste text 10 times
NEXT
Message("The text will be shaded, bolded, italicized, underlined, and
centered.")
TYPE("[ctrlhome][ctrlshiftend]")
Bold()
Italic()
Underline()
Center()
TYPE("[ctrlhome]")
END FUNCTION

See also:

    Bold
    NormalText
    Underline
    WordUnderline




ΓòÉΓòÉΓòÉ 257. Justify ΓòÉΓòÉΓòÉ

This function acts as a toggle to turn justification on or off for a paragraph.
This function is equivalent to choosing Text Alignment Justify.


Syntax
Justify()

Return Value
1  (TRUE) if the text was justified or if justification was removed.
-2  (GeneralFailure) if the alignment was not changed.

Example
FUNCTION Example()
String = "This is a line of Text. "
FOR i = 1 to 10
    Paste()
NEXT
Justify()
END FUNCTION

See also:

    Center
    LeftAlign
    NormalText
    RightAlign



ΓòÉΓòÉΓòÉ 258. KeyInterrupt ΓòÉΓòÉΓòÉ

This function sets a macro function to be called if the user hits a key while
the current macro is running. The called macro function is passed the virtual
key. If the interrupt routine needs to pass information to the main function,
it must pass it through a global variable and the main function must check that
global variable.


Syntax
KeyInterrupt(Function)
Function is the function that runs when a key is pressed. This parameter may
contain the macro file name or the function within that file to call.

Return Value
This function returns the previously set KeyInterrupt function.

Example
FUNCTION Example()
KeyInterrupt("KeyInt")
TYPE("Touch any key")
FOR i = 1 to 5  ' Kill some time.
    FOR j = 1 to 100
    NEXT
    TYPE("{i}.")
NEXT
END FUNCTION

FUNCTION KeyInt(key)
Message("KeyInt {key}")
END FUNCTION

See Also:

    DlgKeyInterrupt
    HourGlass
    MouseInterrupt
    Pause



ΓòÉΓòÉΓòÉ 259. LayoutMode ΓòÉΓòÉΓòÉ

This function changes the current document in Ami Pro from Draft Mode or
Outline Mode to Layout Mode. This function is equivalent to choosing View
Layout Mode.


Syntax
LayoutMode()

Return Value
1  (TRUE) if the view mode was changed.
0  (NoAction) if no action was taken because Ami Pro is already in the mode
selected.

Example
FUNCTION Example()
Mode = GetMode()'What mode is the screen in?
IF Mode != 1
    LayoutMode()'If not Layout Mode, make it so.
ENDIF
END FUNCTION

See also:

    CustomView
    DraftMode
    EnlargedView
    FacingView
    FullPageView
    GetMode
    GetViewLevel
    OutlineMode
    StandardView


ΓòÉΓòÉΓòÉ 260. LCASE ΓòÉΓòÉΓòÉ

This function converts uppercase letters in the source string to lowercase and
returns the resulting string. It does not change punctuation or numbers.


Syntax
LCASE$(Text)
Text is the string that is converted to lowercase.

Return Value
The string with all lowercase letters.

Example
FUNCTION Example()
Again:
Number = Query$("How much was the sale?")
Where = Query$("Where was the sale made (E)ngland, or (A)merica?")
Where = lcase$(Left$(Where, 1))
IF Where = "e"
    Prefix = ""
    Suffix = "╨│"
ELSEIF Where = "a"
    Prefix = "$"
    Suffix = ""
ELSE
    Message("Please choose ""E"" or ""A"".")
    GoTo again
ENDIF
NewNumber = FormatNum$(Prefix, Suffix, 2, Number)
Message("The sale was for {NewNumber}.")
END FUNCTION

See also:

    ASC
    CHR$
    FormatNum$
    Instr
    LEN
    MID$
    strcat$
    strchr
    strfield$
    UCASE$


ΓòÉΓòÉΓòÉ 261. LeaderDots ΓòÉΓòÉΓòÉ

This function applies dots for leader characters in the current table cell or
selected table cells. This function is equivalent to choosing Table Leaders and
selecting dots for the leader type.


Syntax
LeaderDots()

Return Value
1  (TRUE) if the leader dots were applied.
0  (NoAction) if no action was taken.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' create a table
Tables(1, TRUE, 5, 5)
LeaderDots()
TYPE("[Right]")
LeaderHyphs()
TYPE("[Right]")
LeaderLines()
IF Decide("Press OK to remove leaders.")
    TYPE("[Left][Left]")
    FOR i = 1 to 3
       LeaderNone()
       TYPE("[Right]")
    NEXT
ENDIF
END FUNCTION

See also:

    LeaderHyphs
    LeaderLines
    LeaderNone
    TableLayout
    TableLines
    Tables


ΓòÉΓòÉΓòÉ 262. LeaderHyphs ΓòÉΓòÉΓòÉ

This function applies dashes for leader characters in the current table cell or
selected table cells. This function is equivalent to choosing Table Leaders and
selecting dashes for the leader type.


Syntax
LeaderHyphs()

Return Value
1  (TRUE) if the leader dashes were applied.
0  (NoAction) if no action was taken.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' create a table
Tables(1, TRUE, 5, 5)
LeaderDots()
TYPE("[Right]")
LeaderHyphs()
TYPE("[Right]")
LeaderLines()
IF Decide("Press OK to remove leaders.")
    TYPE("[Left][Left]")
    FOR i = 1 to 3
       LeaderNone()
       TYPE("[Right]")
    NEXT
ENDIF
END FUNCTION

See also:

    LeaderDots
    LeaderLines
    LeaderNone
    TableLayout
    TableLines
    Tables


ΓòÉΓòÉΓòÉ 263. LeaderLines ΓòÉΓòÉΓòÉ

This function applies underlines for leader characters in the current table
cell or selected table cells. This function is equivalent to choosing Table
Leaders and selecting underline for the leader type.


Syntax
LeaderLines()

Return Value
1  (TRUE) if the leader dots were applied.
0  (NoAction) if no action was taken.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' create a table
Tables(1, TRUE, 5, 5)
LeaderDots()
TYPE("[Right]")
LeaderHyphs()
TYPE("[Right]")
LeaderLines()
IF Decide("Press OK to remove leaders.")
    TYPE("[Left][Left]")
    FOR i = 1 to 3
       LeaderNone()
       TYPE("[Right]")
    NEXT
ENDIF
END FUNCTION

See also:

    LeaderDots
    LeaderHyphs
    LeaderNone
    TableLayout
    TableLines
    Tables


ΓòÉΓòÉΓòÉ 264. LeaderNone ΓòÉΓòÉΓòÉ

This function turns off the leader characters in the current table cell or
selected table cells. This function is equivalent to choosing Table Leaders
None.


Syntax
LeaderNone()

Return Value
1  (TRUE) if the leader dots were applied.
0  (NoAction) if no action was taken.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
' create a table
Tables(1, TRUE, 5, 5)
LeaderDots()
TYPE("[Right]")
LeaderHyphs()
TYPE("[Right]")
LeaderLines()
IF Decide("Press OK to remove leaders.")
    TYPE("[Left][Left]")
    FOR i = 1 to 3
       LeaderNone()
       TYPE("[Right]")
    NEXT
ENDIF
END FUNCTION

See also:

    LeaderDots
    LeaderHyphs
    LeaderLines
    TableLayout
    TableLines
    Tables


ΓòÉΓòÉΓòÉ 265. Left ΓòÉΓòÉΓòÉ

This function returns the specified number of characters from the left of the
specified string.


Syntax
Left$(Text, Length)
Text is the string to be parsed.
Length is the number of characters from the left end of the string to be
parsed.

Return Value
The specified number of characters from the left end of the string.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the string could not be parsed.

Example
FUNCTION Example()
Message(Left$(Query$("What is your name?"), 5))
END FUNCTION

See also:

    Instr
    MID$
    Right$


ΓòÉΓòÉΓòÉ 266. LeftAlign ΓòÉΓòÉΓòÉ

This function acts as a toggle to turn on or off left alignment for a
paragraph. This function is equivalent to choosing Text Alignment Left.


Syntax
LeftAlign()

Return Value
1  (TRUE) if the text was left aligned, or if alignment was removed.
-2  (GeneralFailure) if the alignment was not changed.

Example
FUNCTION Example()
String = "This is a line of Text. "
FOR i = 1 to 10
    Paste()
NEXT
LeftAlign()
END FUNCTION

See also:

    Center
    Justify
    NormalText
    RightAlign


ΓòÉΓòÉΓòÉ 267. LeftEdge ΓòÉΓòÉΓòÉ

This function scrolls the document to the left edge of the page without moving
the insertion point. This function is equivalent to dragging the slider box on
the horizontal scroll bar to the left using the mouse.


Syntax
LeftEdge()

Return Value
This function returns 0.

Example
FUNCTION Example()
LeftEdge()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 268. LEN ΓòÉΓòÉΓòÉ

This function determines the number of characters in the specified string.


Syntax
LEN(Text)
Text is the string whose length is determined.

Return Value
The length of the string.
0  (FALSE) if the string is empty.

Example
FUNCTION Example()
DEFSTR Char;
' get the name of the open file
OpenFile = GetOpenFileName$()
' get the length of the name
I = len(OpenFile)
' take off the path
WHILE "\" != Assign(&Char, MID$(OpenFile, I, 1))
    I = I - 1
WEND
FileName = Right$(OpenFile, (len(OpenFile) - I))
Message("The current file is {FileName}.")
END FUNCTION

See also:

    FormatNum$
    LCASE$
    Left$
    MID$
    Right$
    strcat$
    strchr
    strfield$
    UCASE$




ΓòÉΓòÉΓòÉ 269. LineDown ΓòÉΓòÉΓòÉ

This function scrolls the document down one line without moving the insertion
point. This function is equivalent to clicking once on the vertical scroll bar
up arrow.


Syntax
LineDown()

Return Value
This function returns 0.

Example
FUNCTION Example()
LineDown()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile



ΓòÉΓòÉΓòÉ 270. LineNumber ΓòÉΓòÉΓòÉ

This function places line numbers in the left margin of the document. This
function is equivalent to choosing Page Line Numbering.


Syntax
LineNumber(Which, Style, Custom)
Which determines the type of line to number and the frequency of the line
numbering. It is a combination of the following values:
Type of line to number:
    Off (0) - Do not number lines
    NumberLines (1) - Number any type of line
    NumberTextLines (128) - Number text lines
Use one of the following in combination with one of the above:
    NumberEvery (2) - Number all lines (of the type selected above)
    NumberEveryOther (4) - Number every other line (of the type selected above)
    NumberEveryFifth (8) - Number every fifth line (of the type selected above)
    NumberEveryCustom (32) - Number every nth line (of the type selected
    above), where n is a custom number
Additional Optional Value:
    ResetEachPage (16) - Reset the numbering sequence on every page of the
    document
Style is the paragraph style to use in determining the spacing for the line
numbering. The Style parameter must be used, even if line numbering is being
turned off.
Custom is the number indicating the frequency of the line numbering.

To display the Line Numbering dialog box to allow the user to choose the line
numbering options: LineNumber

Return Value
1  (TRUE) if the numbering sequence was set.
0  (UserCancel) if the user canceled the function, or if no action was taken.

Example
FUNCTION Example()
LineNumber(3, "Body Text", 0)
END FUNCTION

See also:

    PageNumber





ΓòÉΓòÉΓòÉ 271. LineUp ΓòÉΓòÉΓòÉ

This function scrolls the document up one line without moving the insertion
point. This function is equivalent to clicking once on the vertical scroll bar
down arrow.


Syntax
LineUp()

Return Value
This function returns 0.

Example
FUNCTION Example()
LineUp()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineDown
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 272. LoadOptions ΓòÉΓòÉΓòÉ

This function sets initial display preferences for using Ami Pro. This function
is equivalent to choosing Tools User Setup and choosing Load.


Syntax
LoadOptions(InitialView, Options, StyleSheet)
InitialView determines whether Standard or C ustom  view initially displays.
The InitialView parameter should be set to one of the following options.
    StartCustom (2) - Start in Custom View
    StartStandard (3) - Start in Standard View
Options is a flag variable determining other display defaults.
If any of the following options parameters are set, they take effect when the
program starts. If the options are not set, they do not take effect. Options
can be one or more of the following:
    StartLayout (1) - Start the program in Layout Mode. This value may not be
    combined with StartOutline.
    StartMax (8) - Maximize the Ami Pro window when the program is loaded;
    otherwise, use the previously set window size.
    ShowLogo (64) - Display the Ami Pro logo when the program starts; otherwise
    do not display the logo.
    StartOutline (256) - Start the program in Outline Mode. This value may not
    be combined with StartLayout.
    ShowDesc (1024) - List the style sheets by description name (rather than
    style sheet file name) in the Load Defaults dialog box.
    StartClean (2048) - Start the program in Clean Screen mode.
If StartLayout or StartOutline is not set, the program starts in Draft Mode.
To set multiple options, add the option values together before passing them to
the function.
StyleSheet is the default style sheet to use for new documents.

To show the Load Defaults dialog box and allow the user to select initial
display preferences:
LoadDefaults

Return Value
1  (TRUE) if the load options were successfully set.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the options could not be set.

Example
FUNCTION Example()
LoadOptions(StartStandard, StartLayout, "_MACRO.STY")
END FUNCTION

See also:

    SetDefOptions
    UserSetup
    ViewPreferences


ΓòÉΓòÉΓòÉ 273. LowerCase ΓòÉΓòÉΓòÉ

This function sets lowercase for selected text or for all following text if no
text is selected. It acts as a toggle, turning off lowercase if it is on or
turning on lowercase if it is off. This function is equivalent to choosing Text
Caps Lower Case.


Syntax
LowerCase()

Return Value
1  (TRUE) if the attribute was changed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
LowerCase()
END FUNCTION

See also:

    SmallCaps
    UpperCase


ΓòÉΓòÉΓòÉ 274. MacroEdit ΓòÉΓòÉΓòÉ

This function displays the Edit Macro dialog box. This function is equivalent
to choosing Tools Macros Edit.


A macro must be edited to insert this non-recordable function.

Syntax
MacroEdit()

Return Value
This function returns 1.

Example
FUNCTION Example()
MacroEdit()
END FUNCTION

See also:

    AssignMacroToFile
    ChangeShortcutKey
    MacroOptions
    MacroPlay
    OnKey


ΓòÉΓòÉΓòÉ 275. MacroHelp ΓòÉΓòÉΓòÉ

This function displays the online Ami Pro Macro Documentation Help. This
function is equivalent to choosing Help Macro Doc.


Syntax
MacroHelp()

Return Value
1  (TRUE) if the macro Help window displayed.
-2  (GeneralFailure) if the macro Help window could not be displayed for some
reason other than insufficient memory.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
MacroHelp()
END FUNCTION

See also:

    About
    Help
    HowDoIHelp
    UsingHelp



ΓòÉΓòÉΓòÉ 276. MacroOptions ΓòÉΓòÉΓòÉ

This function displays the Quick Record Macro Options dialog box. This function
is equivalent to choosing Tools Macros Record and choosing Options. The dialog
box allows you to select shortcut keys for Quick Macro Record and Quick Macro
Play.


A macro must be edited to insert this non-recordable function.

Syntax
MacroOptions()

Return Value
This function returns 1.

Example
FUNCTION Example()
MacroOptions()
END FUNCTION

See also:

    AssignMacroToFile
    ChangeShortcutKey
    MacroEdit
    MacroPlay
    OnKey


ΓòÉΓòÉΓòÉ 277. MacroPlay ΓòÉΓòÉΓòÉ

This function displays the Play Macro dialog box. This function is equivalent
to choosing Tools Macros Playback.

A macro must be edited to insert this non-recordable function.

Syntax
MacroPlay()

Return Value
This function returns 1.

Example
FUNCTION Example()
MacroPlay()
END FUNCTION

See also:

    AssignMacroToFile
    ChangeShortcutKey
    MacroEdit
    MacroOptions
    OnKey


ΓòÉΓòÉΓòÉ 278. ManualFrame ΓòÉΓòÉΓòÉ

This function displays the frame arrow and allows the user to manually create a
frame. This function is equivalent to choosing Frame Create Frame and choosing
Create Manually.


Syntax
ManualFrame()

Return Value
This function returns 1.

Example
FUNCTION Example()
ManualFrame()
END FUNCTION

See also:

    AddFrame
    AddFrameDlg
    FrameLayout
    FrameModBorders
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType
    IsFrameSelected
    SelectFrameByName
    SetFrameDefaults


ΓòÉΓòÉΓòÉ 279. MarkBookMark ΓòÉΓòÉΓòÉ

This function allows the user to add a bookmark, remove a bookmark, or go to a
specific bookmark. This function is equivalent to choosing Edit Bookmarks.


Syntax
MarkBookMark(Name, Which)
Name is the name of the new bookmark.
Which is the desired bookmark function and can be one of the following:
    AddBookmark (4003) - Add a new bookmark with the name provided
    DeleteBookmark (4004) - Remove the named bookmark
    FindBookmark (4002) - Go to the named bookmark

To display the Bookmarks dialog box to allow the user to select the bookmark
function and name: MarkBookMark

Return Value
1  (TRUE) if the bookmark function was successfully completed.
-2  (GeneralFailure) if the bookmark function could not be completed.

Example
FUNCTION Example()
MarkBookMark("Example", AddBookmark)
TYPE("[CtrlEND]")
PageNo = GetPageNo()
MarkBookMark("Example", FindBookmark)
Text = GetMarkText$()
MarkBookMark("Example", DeleteBookmark)
IF Text != ""
    Message("Your bookmark was named ""{Text}"", and there are {PageNo} pages
 in this document.")
ENDIF
END FUNCTION

See also:

    GetMarkText$
    GoToCmd



ΓòÉΓòÉΓòÉ 280. MarkIndexWord ΓòÉΓòÉΓòÉ

This function displays the Mark Index Entry dialog box to allow you to mark
selected text for inclusion in the index. This function is equivalent to
choosing Edit Mark Text Index Entry.

To automatically mark a word for the index, use the FieldAdd function. To
automatically remove an index entry, use the FieldRemove function.

Syntax
MarkIndexWord

Return Value
This function returns 0.

Example
FUNCTION Example()
MarkIndexWord
END FUNCTION

See also:

    FieldAdd
    FieldRemove
    Generate
    SetIndexFile


ΓòÉΓòÉΓòÉ 281. MarkTOCEntry ΓòÉΓòÉΓòÉ

This function displays the TOC Entry dialog box to allow you to mark selected
text for a table of contents entry. This function is equivalent to choosing
Edit Mark Text TOC Entry.


To automatically add a TOC entry, use the FieldAdd function. To automatically
remove a TOC entry, use the FieldRemove function.

Syntax
MarkTOCEntry

Return Value
This function returns 0.

Example
FUNCTION Example()
MarkTOCEntry
END FUNCTION

See also:

    FieldAdd
    FieldRemove
    Generate
    SetTOCFile
    TOCOptions


ΓòÉΓòÉΓòÉ 282. MasterDoc ΓòÉΓòÉΓòÉ

This function displays the Master Document dialog box and allows you to select
files to add or remove from the master document. This function is equivalent to
choosing File Master Document.


This function does not automatically add or remove files from the master
document. You can use the SetMasterFiles function to add or remove files from
the master document.

Syntax
MasterDoc

Return Value
This function returns 0.

Example
FUNCTION Example()
MasterDoc
END FUNCTION

See also:

    GetMasterFilesCount
    GetMasterFiles
    SetIndexFile
    SetMasterFiles
    SetTOCFile
    TOCOptions




ΓòÉΓòÉΓòÉ 283. Maximize ΓòÉΓòÉΓòÉ

This function maximizes the Ami Pro window, causing it to fill the entire
screen. This function is equivalent to choosing System Maximize. If the window
size is already maximized, executing this function restores the previous screen
size. All other windows are moved behind the Ami Pro window when this function
is executed.


Syntax
Maximize()

Return Value
This function does not return a value.

Example
FUNCTION Example()
Maximize()
END FUNCTION

See also:

    Minimize
    Restore


ΓòÉΓòÉΓòÉ 284. Merge ΓòÉΓòÉΓòÉ

This function merges a merge document with a data file. This function is
equivalent to choosing File Merge, selecting option 3, choosing OK, and then
selecting Merge & print. Using this function sends the merge documents to the
printer.


Before using the merge function, your macro should ensure that the merge
document you want to merge to is on the screen.

Syntax
Merge(Flag, RecFile[, DescFile][, SelectionKey, SelectionKey, Operator,
FieldNumber, NextOp...])
Flag is a number that defines which optional parameters are used and can be one
of the following:
    (0) - 0 selection criteria given
    (1) - 1 selection criterion given
    (2) - 2 selection criteria given
    (3) - 3 selection criteria given
    Description (8) - This merge uses a description file and includes the
    description filename
The number of criteria used (0 - 3) should be added to the description value to
make up the value of the Flag parameter.
RecFile is the data file the merge document is merged with.
DescFile is the optional description file used when the data file is not an Ami
Pro file. The DescFile should be used as the next parameter only if a
description file is used.
SelectionKey is a string or number to use in the selection of records to merge.
The compare key is a string, if using an alphanumeric comparison, or a number,
if using a numeric comparison.
Operator is the operator to use in the selection comparison and can be one of
the following values.
    Equal (0) - The field's value must be equal to the key to merge.
    LessThan (1) - The field's value must be less than the key to merge.
    GreaterThan (2) - The field's value must be greater than the key to merge.
    NotEqual (3) - The field's value must be different than the key to merge.
    Lteq (4) - The field's value must be less than or equal to the key to
    merge.
    Gteq (5) - The field's value must be greater than or equal to the key to
    merge.
FieldNumber is the number of the field to use for this selection. It is zero
based. To compare against the first field in the data file, set field number to
0.
NextOp is a number that defines whether to select based on this criterion AND
the next one, or this one OR the next one. If there are no more specifications
this field should be zero. The values for this field are:
    AndNext (1) - This selection AND the following selection must match to
    merge this record.
    OrNext (2) - This selection OR the following selection must match to merge
    this record.

To display the Merge dialog box and allow the user to set merge specifications:
Merge

Return Value
1  (TRUE) if the merge was completed.
0  (UserCancel) if the user canceled the function.
-3  if the input was invalid.
-2  (GeneralFailure) if the merge failed.

Example
FUNCTION Example()
Merge(0, "TEST.SAM")
END FUNCTION

See also:

    MergeAction
    MergeMacro
    MergeToFile


ΓòÉΓòÉΓòÉ 285. MergeAction ΓòÉΓòÉΓòÉ

This function is used in conjunction with the MergeMacro function to decide
whether a merge document should be printed, not printed, canceled, or the rest
of the documents should be printed. This function is equivalent to choosing
File Merge, selecting option 3, choosing OK, and then selecting Merge, view &
print.


This function must be called once for each record merged and again after either
the end of the data file has been reached or the user cancels the printing of
the merged records.

Syntax
MergeAction(Which)
Which is the action to take on the merged document and can be one of the
following:
    PrintDoc (1) - Print this one
    MergeNext (2) - Do not print this one; prepare the next one
    MergeCont (3) - Print this one; print the rest of them without stopping
    MergeStop (4) - Do not print this one; cancel the rest of the merge

To display the Merge dialog box and allow the user to set merge specifications:
Merge

Return Value
1  (TRUE) if the record was merged.
0  (UserCancel/FALSE) at the end of the data file, or if the user cancels
printing of the merged record following a PrintDoc or MergeCont.
-2  (GeneralFailure) if the record was not merged.

Example
FUNCTION Example()
docdir = GetDocPath$()
datafile = "{docdir}mercdata.sam"
descfile = ""
'configure mergefile for printing
MergeMacro(24, datafile, descfile)
'do not actually print them; this associates the datafile
MergeAction(mergestop)
END FUNCTION

See also:

    Merge
    MergeMacro
    MergeToFile


ΓòÉΓòÉΓòÉ 286. MergeMacro ΓòÉΓòÉΓòÉ

This function merges a merge document with a data file, then allows the macro
to examine the merged document, edit it, and decide if it should be printed.
This function is equivalent to choosing File Merge, selecting option 3,
choosing OK, and then selecting Merge, view & print. Once the first document
has been merged, the MergeAction function is used to decide what should be done
with the document. This function is equivalent to choosing the dialog box that
appears onscreen during Merge, view & print.


Before using the merge function, your macro should ensure that the merge
document you want to merge to is on the screen.

Syntax
MergeMacro(Flag, RecFile[, DescFile][, SelectionKey, SelectionKey, Operator,
FieldNumber, NextOp...])
Flag is a number that defines which optional parameters are used and can be one
of the following:
    (0) - 0 selection criteria given
    (1) - 1 selection criterion given
    (2) - 2 selection criteria given
    (3) - 3 selection criteria given
    Description (8) - This merge uses a description file and includes the
    description filename
The number of criteria used (0-3) should be added to the description value to
make up the value of the Flag parameter.
RecFile is the data file the merge document is merged with.
DescFile is the description file used when the data file is not an Ami Pro
file.
SelectionKey is a string or number to use in the selection of records to merge.
The compare key is a string, if using an alphanumeric comparison, or a number,
if using a numeric comparison.
Operator is the operator to use in the selection comparison and can be one of
the following values:
    Equal (0) - The field's value must be equal to the key to merge.
    LessThan (1) - The field's value must be less than the key to merge.
    GreaterThan (2) - The field's value must be greater than the key to merge.
    NotEqual (3) - The field's value must be different than the key to merge.
    Lteq (4) - The field's value must be less than or equal to the key to
    merge.
    Gteq (5) - The field's value must be greater than or equal to the key to
    merge.
FieldNumber is the number of the field to use for this selection. It is zero
based. To compare against the first field in the data file, set field number to
0.
NextOp is a number that defines whether to select based on this criterion AND
the next one, or this one OR the next one. If there are no more specifications
this field should be zero. The values for this field are:
    AndNext (1) - This selection AND the following selection must match to
    merge this record.
    OrNext (2) - This selection OR the following selection must match to merge
    this record.

To display the Merge dialog box and allow the user to set merge specifications:
Merge

Return Value
1  (TRUE) if the merge was completed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the merge failed.

Example
FUNCTION Example()
docdir = GetDocPath$()
datafile = "{docdir}mercdata.sam"
descfile = ""
'configure mergefile for printing
MergeMacro(24, datafile, descfile)
'do not actually print them; this associates the datafile
MergeAction(mergestop)
END FUNCTION

See also:

    MergeAction
    Merge
    MergeToFile


ΓòÉΓòÉΓòÉ 287. MergeToFile ΓòÉΓòÉΓòÉ

This function merges a merge document with a data file and places the result in
another file for later editing or printing. This function is equivalent to
choosing File Merge, selecting option 3, choosing OK, and then selecting Merge
& save as.


Before using the merge function, your macro should ensure that the merge
document you want to merge to is on the screen.

Syntax
MergeToFile(Flag, RecFile, OutFile[, DescFile][, SelectionKey, SelectionKey,
Operator, FieldNumber, NextOp]...)
Flag is a number that defines which optional parameters are used. The  flag
parameter defines which of the optional parameters are used, according to the
following list:
    (0) - 0 selection criteria given
    (1) - 1 selection criterion given
    (2) - 2 selection criteria given
    (3) - 3 selection criteria given
    Description (8) - This merge uses a description file, and includes the
    description filename
    ToFile (32) - This merge is merged to a file
The number of criteria used (0 - 3) must be added to the description value.
Because this file merges, 32 must be added to this result to make up the value
of the  flag parameter.
RecFile is the data file the merge document is merged with.
OutFile is the file to which the merged document is saved.
DescFile is the description file used when the data file is not an Ami Pro
file.
SelectionKey is a string or number to use in the selection of records to merge.
The compare key is a string, if using an alphanumeric comparison, or a number,
if using a numeric comparison.
Operator is the operator to use in the selection comparison and can be one of
the following values:
    Equal (0) - The field's value must be equal to the key to merge.
    LessThan (1) - The field's value must be less than the key to merge.
    GreaterThan (2) - The field's value must be greater than the key to merge.
    NotEqual (3) - The field's value must be different than the key to merge.
    Lteq (4) - The field's value must be less than or equal to the key to
    merge.
    Gteq (5) - The field's value must be greater than or equal to the key to
    merge.
FieldNumber is the number of the field to use for this selection. It is zero
based. To compare against the first field in the data file, set field number to
0.
NextOp is a number that defines whether to select based on this criterion AND
the next one or this one OR the next one. If there are no more specifications,
this field should be zero. The values for this field are:
    AndNext (1) - This selection AND the following selection must match to
    merge this record.
    OrNext (2) - This selection OR the following selection must match to merge
    this record.

To display the Merge dialog box and allow the user to set merge specifications:
Merge

Return Value
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the merge failed.

Example
FUNCTION Example()
MergeToFile(32 "mrgdata.SAM"  "output.SAM")
END FUNCTION

See also:

    MergeAction
    Merge
    MergeMacro


ΓòÉΓòÉΓòÉ 288. Message ΓòÉΓòÉΓòÉ

This function displays a message box with the specified title, prompt, and an
OK push button. It waits for the user to acknowledge the message by selecting
OK. You can use a message box to display information for the user.


Syntax
Message(Prompt[, Title])
Prompt is a string used as a prompt to the user. It can be a maximum of 80
characters.
Title is the title for the message box. The default is "Ami Pro Macro".

Return Value
This function does not return a value.

Example
FUNCTION Example()
name = "Mark Olsen"
Message("Hello, {name}.", "My Message")
END FUNCTION

See also:

    Decide
    DialogBox
    Messages
    Query$
    UserControl


ΓòÉΓòÉΓòÉ 289. Messages ΓòÉΓòÉΓòÉ

This function allows you to determine whether the user should respond to
certain program messages during macro execution. Many Ami Pro functions display
message boxes asking the user to confirm an action before it is taken. If
messages display is off, the macro forces Ami Pro to take the default action
proposed by the message box (as if the user had pressed ENTER). If messages
display is on, the message box displays, and the user needs to intervene before
macro execution can continue.


If a specific reply is required to a specific message, the AnswerMsgBox
function must be used to reply to a specific function.

Syntax
Messages(State)
State determines whether unexpected messages appear during macro execution.
    On (1)  - Display the messages
    Off (0) - Accept the default replies and not display the messages

Return Value
This function does not return a value.

Example
FUNCTION Example()
Messages(Off)
FileClose()
Messages(On)
END FUNCTION

See also:

    AnswerMsgBox
    IgnoreKeyboard
    SingleStep
    UserControl


ΓòÉΓòÉΓòÉ 290. MID ΓòÉΓòÉΓòÉ

This function is used to extract a portion of a string.


Syntax
MID$(Text, Offset, Length)
Text is the string from which a shorter string is extracted.
Offset is the location in the specified string to start parsing the new string.
Offset is one based; to extract from the beginning of the longer string, use an
offset of 1 or the function Left$.
Length is the number of characters to extract out of the specified string.

Return Value
The requested text.
The null string ("") if the starting offset is beyond the end of the larger
string.

Example
FUNCTION Example()
txt="Hello, my name is Susan Butler."
newtext=MID$(txt, 7, 11)
Message(newtext)  'returns "my name is"
END FUNCTION

See also:

    ASC
    CHR$
    FormatNum$
    LCASE$
    Left$
    LEN
    strcat$
    strchr
    strfield$
    UCASE$


ΓòÉΓòÉΓòÉ 291. Minimize ΓòÉΓòÉΓòÉ

This function minimizes the Ami Pro window by reducing it to an icon. This
function is equivalent to choosing System Minimize. If the window is already
reduced to an icon, executing this function restores the previous window size.
When Ami Pro is minimized, macro execution continues in the background.


Syntax
Minimize()

Return Value
This function does not return a value.

Example
FUNCTION Example()
Minimize()
END FUNCTION

See also:

    Maximize
    Restore


ΓòÉΓòÉΓòÉ 292. Mod ΓòÉΓòÉΓòÉ

This function returns the remainder of the first parameter divided by the
second.


Syntax
Mod(Numerator, Denominator)
Numerator is the number to be divided.
Denominator is the number to divide into the numerator.

Return Value
The remainder of the numerator divided by the denominator
-2  (GeneralFailure) if the numbers could not be divided

Example
FUNCTION Example()
Top = Query$("Enter the value for the numerator:")
Bottom = Query$("Enter the value for the denominator:")
Result = Mod(Top, Bottom)
Message(Result)
END FUNCTION

See also:

    IsNumeric
    Round


ΓòÉΓòÉΓòÉ 293. ModifyAlignment ΓòÉΓòÉΓòÉ

This function modifies paragraph style alignment options. This function is
equivalent to choosing Style Modify Style and choosing Alignment.


ModifySelect should be called before this function to define the style to
modify.

Before the new alignment options take effect for the selected paragraph style,
the ModifyReflow function should be called in the macro.

Syntax
ModifyAlignment(Options, AllLevel, FirstLevel, RestLevel, 0, RightIndent)
Options is a flag parameter containing the paragraph style's alignment options.
Set the Options parameter to one or more of the following options:
    AlignLeft (1) - Left align the paragraph
    AlignRight (2) - Right align the paragraph
    AlignCenter (4) - Center the paragraph
    AlignJustify (8) - Justify the paragraph
    IndentBoth (16) - Indent both sides of the paragraph
    NoIndentAll (32) - Do not use entire paragraph indention option
    NoIndentFirst (64) - Do not use first line indention option
    NoIndentRest (128) - Do not use rest of lines indention options
    HangingIndent (512) - This paragraph has a hanging indent
One of the four alignment options should always be chosen. Multiple options
should be added together before they are passed to the function. All levels are
in twips (1 inch = 1440 twips).
AllLevel is the level to indent all lines in the paragraph. This parameter is
ignored if the NoIndentAll flag is set.
FirstLevel is the level to indent the first line of the paragraph. This
parameter is ignored if the NoIndentFirst flag is set.
RestLevel is the level to indent the rest of the lines in the paragraph. This
parameter is ignored if the NoIndentRest flag is set.
RightIndent is the level to indent all lines in the paragraph from the right.
This parameter is ignored if the NoIndentRest flag is set.

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

To modify the tabs used when modifying the style, refer to the ModifyBreaks
function.

Return Value
1  (TRUE) if the alignment options were set.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the options were not set.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable


ΓòÉΓòÉΓòÉ 294. ModifyBreaks ΓòÉΓòÉΓòÉ

This function modifies paragraph style page break options. This function is
equivalent to choosing Style Modify Style and choosing Breaks.


ModifySelect should be called before this function to define the style to
modify.

Before the new page break options take effect for the selected paragraph style,
the ModifyReflow function must be called in the macro.

Syntax
ModifyBreaks(Options, Style, NumTabs[, Type, Offset])
Options is a flag parameter specifying the break options. Set the Options
parameter to one or more of the following options:
    NoBreaks (0) - Do not allow page breaks within this paragraph
    PageBreakBefore (1) - Put a page break before this paragraph
    PageBreakAfter (2) - Put a page break following this paragraph
    BreakWithin (4) - Allow page breaks within the paragraph
    KeepPrevious (8) - Keep this paragraph with the previous paragraph
    KeepNext (16) - Keep this paragraph with the next paragraph
    UseStyleTabs (32) - Selects Use style tabs for the specified paragraph
    style
    (64) - If set, the style defined in the Style parameter is applied to the
    next paragraph
    ColBreakBefore (128) - Put a column break before this paragraph
    ColBreakAfter (256) - Put a column break after this paragraph
One of the four break options should always be chosen. The KeepPrevious option
may be chosen if the NoBreak, PageBreakAfter, or ColBreakAfter option is
chosen. The KeepNext option may be chosen if the NoBreak, PageBreakBefore, or
ColBreakBefore option is chosen.
Style is the paragraph style to use for the next paragraph. The next style (64)
option must also be set in order to apply this paragraph style.
NumTabs specifies the number of tabs settings that follow.
You must enter a Type and Offset for each tab.
Type is the type of tab. The Offset parameter must also be used for each tab.
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
To display leaders preceding the tab, add one of the following values to the
type of tab:
    TabHyph (16384) - Displays hyphens
    TabDot (32768) - Displays dots
    TabLine (49152) - Displays a line
Offset is the distance of the tab from the left margin and must be given in
twips (1 inch = 1440 twips). The Type parameter must be used for each tab.

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

Return Value
1  (TRUE) if the break options were set.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the options were not set.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable


ΓòÉΓòÉΓòÉ 295. ModifyEffects ΓòÉΓòÉΓòÉ

This function modifies paragraph style bullets and numbers. This function is
equivalent to choosing Style Modify Style and choosing Bullets/Numbers.


ModifySelect should be called before this function to define the style to
modify.

Before the new bullets and numbering options take effect for the selected
paragraph style, the ModifyReflow function must be called in the macro.

Syntax
ModifyEffects(Text, Spacing, Indent, Attr, LevelNum, Align, 0)
Text is the leading text for the paragraph. The Text parameter specifies the
text, bullet, or numbers that precede each paragraph using this paragraph
style. The text must be typed as it would appear in the edit box in the
Bullets/Numbers panel in the Modify Style dialog box. Bullets can be inserted
by typing the following text where the bullet should be placed:
    <Γòû1> - Small  Round Bullet
    <Γòû2> - Large  Round Bullet
    <Γòû3> - Small  Square Bullet
    <Γòû4> - Large  Square Bullet
    <Γòû5> - Large  Outline Square Bullet
    <Γòû6> - Small  Diamond Bullet
    <Γòû7> - Large  Diamond Bullet
    <Γòû8> - Small  Open Circle Bullet
    <Γòû9> - Large  Open Circle Bullet
    <Γòû10> - Check  Mark
    <Γòû11> - Tack
    <Γòû12> - Square shadow below bullet
    <Γòû13> - Square shadow above bullet
    <Γòû14> - Check box
    <Γòû15> - Square with X bullet
    <Γòû16> - Rounded arrowhead top shaded
    <Γòû17> - Rounded arrowhead bottom shaded
To type the dot in front of the bullet number, turn on Num Lock, hold the ALT
key, type 0183 and release the ALT key.
Numbers can be inserted by typing the following text where the number should be
inserted:
    <#1> - 1 2 3 4 5...
    <#2> - A B C D E...
    <#3> - a b c d e...
    <#4> - I II III IV V...
    <#5> - i ii iii iv v...
    <#6> - * ** *** ****...
Spacing is a flag indicating how to space between the text and the paragraph
body. The Spacing parameter should be set to one of the following options:
    TabIndent (0) - Separate leading text from body with a tab
    SpaceIndent (1) - Separate leading text from body with the space specified
    in the Indent parameter
Indent is the amount of space to use between the text and the paragraph body.
The SpaceIndent option should be set for this spacing to be used.
The amount of indention must be given in twips (1 inch = 1440 twips).
The right alignment option must have enough indention space to line up on the
right. For example, when using asterisks, there must be enough space to line up
on the rightmost asterisk.
Attr is a flag parameter specifying the attribute options for the leading text
and can be one of the following:
    NormalAttr (0) - Text has no attributes
    BoldText (4) - Bold text
    ItalicText (8) - Italicized text
    UnderlineText (16) - Underlined text
    WordUnderlineText (32) - Word underlined text
    UpperCase (2048) - Capitalized text
    SuperScript (64) - Superscripted text
Multiple attributes can be added together. Not all fonts have all attributes
and the underline attributes cannot be combined.
LevelNum is the outlining level number to use and should be a number from 0 to
9. If this is not an outline style, this option should be set to 0.
Align is a flag determining whether to right align the text in the special
effect and can be one of the following:
    (0) - Do not right align
    (16) - Right align

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

Return Value
1  (TRUE) if the effects options were set.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the options were not set.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyBreaks
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable


ΓòÉΓòÉΓòÉ 296. ModifyFont ΓòÉΓòÉΓòÉ

This function modifies paragraph style font. This function is equivalent to
choosing Style Modify Style and choosing Font. Through the menu commands, the
user can only select from the fonts available on the printer. Using the macro
commands, any type of font can be requested.


ModifySelect should be called before this function to define the style to
modify.

Before the new font options take effect for the selected paragraph style, the
ModifyReflow function must be called in the macro.

Syntax
ModifyFont(FontName, Size, Color, Options)
FontName is the name of the font as listed in the Face list box.
Size is the size of the font, in twips. The formula for finding the proper
point size is pointsize * 20 = twips.
Color is the color of the font and can be one of the following:
    White (16777215) - White
    Cyan (16776960) - Light blue
    Yellow (65535) - Yellow
    Magenta (16711935) - Purple
    Green (65280) - Green
    Red (255) - Red
    Blue (16711680) - Blue
    Black (0) - Black
Options is a flag parameter specifying the attribute options and can be one or
more of the following:
    NormalAttr (0) - Text has no attributes
    BoldText (4) - Bold text
    ItalicText (8) - Italicized text
    UnderlineText (16) - Underlined text
    WordUnderlineText (32) - Word underlined text
    UpperCase (2048) - All caps text
    DoubleLineAttr (256) - Double underline text
    VarPitch (1) - Variable pitch font
    Serifs (1024) - Serifs in font
Multiple attributes can be added together. Not all the fonts have all the
attributes and some attributes, such as the caps attributes and the underline
attributes, cannot be combined.

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

Return Value
1  (TRUE) if the font options were set.
-2  (GeneralFailure) if the options were not set.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable



ΓòÉΓòÉΓòÉ 297. ModifyLayout ΓòÉΓòÉΓòÉ

This function displays the Modify Page Layout dialog box. This function is
equivalent to choosing Page Modify Page and choosing Layout. This function does
not automatically modify the page layout.


You must be in Layout Mode to use this function.

Syntax
ModifyLayout()

Return Value
1  (TRUE) if the page layout was modified.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the layout was not modified.

Example
FUNCTION Example()
ModifyLayout()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage



ΓòÉΓòÉΓòÉ 298. ModifyLines ΓòÉΓòÉΓòÉ

This function modifies paragraph style lines. This function is equivalent to
choosing Style Modify Style and choosing Lines.


ModifySelect should be called before this function to define the style to
modify.

Before the new line options take effect for the selected paragraph style, the
ModifyReflow function must be called in the macro.

Syntax
ModifyLines(Options, StyleAbove, SpaceAbove, StyleBelow, SpaceBelow, Length,
Color, 0)
Options is a flag parameter specifying the line options. The Options parameter
consists of one or more of the following options:
    Off (0) - No lines above or below
    LineAbove (1) - Put a line above the paragraph
    LineBelow (2) - Put a line below the paragraph
    LengthOfText (4) - Line is the length of the text
    LengthMargins (8) - Line is the length of the margins
    LengthCustom (16) - Line's length is determined by the  length parameter
StyleAbove and StyleBelow determine the type of line to print above and below
the paragraph, respectively. Available line styles are:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rules
    DoubleTwoPoint (9) - Parallel two point rules
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
SpaceAbove is the spacing between the font and the line above the text, in
twips. If none, use 0 for this parameter.
SpaceBelow is the spacing between the font and the line below the text, in
twips. If none, use 0 for this parameter.
Length is the length of the line, in twips, if a custom length.
Color is the color of the line and can be one of the following:
    White (16777215) - White
    Cyan (16776960) - Light blue
    Yellow (65535) - Yellow
    Magenta (16711935) - Purple
    Green (65280) - Green
    Red (255) - Red
    Blue (16711680) - Blue
    Black (0) - Black
    DarkGray (12566463) - 90% gray scale
    MediumGray (8355711) - 50% gray scale
    LightGray (4144959) - 20% gray scale
    VeryLightGray (1644825) - 10% gray scale

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

Return Value
1  (TRUE) if the line options were set.
-2  (GeneralFailure) if the options were not set.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable




ΓòÉΓòÉΓòÉ 299. ModifyReflow ΓòÉΓòÉΓòÉ

This function applies changes that have been made to paragraph styles using the
other modify paragraph style functions. This function should be called after
using the modify paragraph style functions and before editing other text. This
function is equivalent to choosing Style Modify Style.


This function should be called after using other modify paragraph style
functions.

Syntax
ModifyReflow()

Return Value
1  (TRUE) if the changed paragraph styles were applied.
-2  (GeneralFailure) if the paragraph styles were not applied.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifySelect
    ModifySpacing
    ModifyStyle
    ModifyTable





ΓòÉΓòÉΓòÉ 300. ModifySelect ΓòÉΓòÉΓòÉ

This function selects a paragraph style to modify. The other  Modify  Paragraph
Style functions act on the paragraph style selected by this function. This
function is the equivalent to choosing Style Select a Style.


This function should be called prior to using other modify paragraph style
functions.

Syntax
ModifySelect(Style)
Style is the name of an existing paragraph style.

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

Return Value
1  (TRUE) if the paragraph style was selected.
-2  (GeneralFailure) if the paragraph style was not selected.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySpacing
    ModifyStyle
    ModifyTable


ΓòÉΓòÉΓòÉ 301. ModifySpacing ΓòÉΓòÉΓòÉ

This function modifies paragraph style spacing. This function is equivalent to
choosing Style Modify Style and choosing Spacing.


ModifySelect should be called before this function to define the style to
modify.

Before the new spacing options take effect for the selected paragraph style,
the ModifyReflow function must be called in the macro.

Syntax
ModifySpacing(Options, Amount, ParaAbove, ParaBelow, Tightness, 0, 0)
Options is a flag parameter with spacing options. The  options parameter should
be set to one of the following options:
    SingleSpacing (1) - Use single line spacing
    OneOneHalfSpacing (2) - One and one half line spacing
    DoubleSpacing (4) - Double line spacing
    CustomSpacing (8) - Custom line spacing
    AddAlways (16) - Always use line above spacing
    AddNotBreak (32) - Use line above spacing only if not at page break
Amount is the line spacing to use if custom spacing is selected.
ParaAbove is the spacing to use above the paragraph, in twips (1 inch = 1440
twips).
ParaBelow is the spacing to use below the paragraph, in twips (1 inch = 1440
twips).
Tightness is the line tightness factor to use and can be one of the following:
    TightLines (90) - 90% line tightness
    NormalLines (100) - 100% line tightness (normal)
    LooseLines (115) - 115% line tightness

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

Return Value
1  (TRUE) if the spacing was set.
-2  (GeneralFailure) if the spacing was not set.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifyStyle
    ModifyTable


ΓòÉΓòÉΓòÉ 302. ModifyStyle ΓòÉΓòÉΓòÉ

This function displays the Modify Style dialog box. This function is equivalent
to choosing Style Modify Style, but it cannot automatically modify a paragraph
style. To allow the macro to modify paragraph styles directly, use the other
modify paragraph style functions.


Syntax
ModifyStyle()

Return Value
1  (TRUE) if the paragraph style was modified.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the paragraph style could not be modified.

Example
FUNCTION Example()
ModifyStyle()
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    GetStyleName$
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyTable


ΓòÉΓòÉΓòÉ 303. ModifyTable ΓòÉΓòÉΓòÉ

This function modifies paragraph style table format. This function is
equivalent to choosing Style Modify Style and choosing Table.


ModifySelect should be called before this function to define the style to
modify.

Before the new table format options take effect for the selected paragraph
style, the ModifyReflow function must be called in the macro.

Syntax
ModifyTable(CellFormat, Decimals, DecimalPoint, Separator, CurrencySymbol,
Options)
CellFormat determines the cell format and can be one of the following:
    GeneralFormat (1) - Show decimals only if required
    FixedFormat (2) - Show a fixed number of decimals
    CurrencyFormat (3) - Show the currency symbol
    PercentFormat (4) - Display the number with a percent sign
Decimals is the number of decimal places to display for numbers.
DecimalPoint is the character to use for the decimal point.
Separator is the character to use as the thousands separator.
CurrencySymbol is the character to use for the currency symbol.
Options is a flag parameter with table format options and can be one of the
following:
    ThousandsSep (8) - Use thousands separator character. The
    ThousandsSeparator option should be set if thousands separators are to
    display and print.
    LeadingNegative (16) - Use leading minus to indicate negative numbers
    TrailingNegative (32) - Use trailing minus to indicate negative numbers
    ParenthesesNegative (64) - Use parentheses to indicate negative numbers
    RedNegative (128) - Negative numbers appear in red
    CurrencyLead (256) - Place currency symbol ahead of number
    CurrencyTrail (0) - Place currency symbol after number
Either LeadingNegative, TrailingNegative, or ParenthesesNegative should be
chosen to determine how to display negative numbers. The RedNegative option can
be used to display and print negative numbers in red. Either the CurrencyLead
or CurrencyTrail option should be used to indicate the position of the currency
symbol.

To display the Modify Style dialog box and allow the user to select the options
for modifying paragraph styles: ModifyStyle

Return Value
1  (TRUE) if the table options were set.
-2  (GeneralFailure) if the options were not set.

Example
FUNCTION Example()
NewName = Query$("What do you want to name the new style?", "TestStyle")
BaseName = GetStyleName$()
CreateStyle(NewName, BaseName, 0)
ModifySelect(NewName)
ModifyAlignment(AlignLeft, 0, 0, 0, 0, 0)
ModifyBreaks(4, 0, 0)
ModifyEffects("<#1>", 1, 1440, UpperCase, 0, 16, 0)
ModifySpacing(2, 0, 0, 0, 90, 0, 0)
ModifyTable(3, 2, ".", ",", "$", (8 + 16 + 128 + 256))
ModifyLines(1, 2, 180, 0, 0, 1440, 65535, 0)
ModifyFont("Times New Roman", (20 * 20), 255, UpperCase)
SetStyle(NewName)
ModifyReflow()
TYPE("This[Enter]is what the new[Enter]style looks[Enter]Like...[Enter]")
SetStyle(BaseName)
END FUNCTION

See also:

    CreateStyle
    DefineStyle
    ModifyAlignment
    ModifyBreaks
    ModifyEffects
    ModifyFont
    ModifyLines
    ModifyReflow
    ModifySelect
    ModifySpacing
    ModifyStyle


ΓòÉΓòÉΓòÉ 304. ModLayoutFinish ΓòÉΓòÉΓòÉ

This function applies changes to the page layout after the function
ModLayoutInit has been run. This function is equivalent to accepting changes
entered by choosing Page Modify Page Layout.


You must call this function after calling ModLayoutInit.

Syntax
ModLayoutFinish()

Return Value
1  (TRUE) if the changes were accepted.
-2  if the changes were not accepted.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage





ΓòÉΓòÉΓòÉ 305. ModLayoutInit ΓòÉΓòÉΓòÉ

This function prepares Ami Pro to accept page layout changes. This function is
equivalent to initializing changes made when choosing Page Modify Page Layout.


This function must be called prior to any modify page layout functions.

You must call this function before calling ModLayoutFinish.

Syntax
ModLayoutInit(Type)
Type is the type of page setup and can be the following:
    (512) - All pages

Return Value
1  (TRUE) if the initialization for changes was successful.
-2  (GeneralFailure) if the initialization failed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage




ΓòÉΓòÉΓòÉ 306. ModLayoutLeftFooter ΓòÉΓòÉΓòÉ

This function modifies the left footer information for the current page layout
if the current page layout is not for all pages. This function is equivalent to
choosing Page Modify Page Layout, choosing Footer, and choosing Left only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutLeftFooter(LeftMargin, TopMargin, RightMargin, BottomMargin, 0, Flag,
NumCols, NumTabs[, Type, Offset])
LeftMargin is the distance from the left edge of the paper.
TopMargin is the distance from the top edge of the paper.
RightMargin is the distance from the right edge of the paper.
BottomMargin is the distance from the bottom edge of the paper.
The margin parameters are in twips and represent how much space to leave on
that edge of the paper.
Flag is an options parameter and can have one or more of the following values:
    (1) - Balance (if multi-column)
    (2) - Gutterline (if multi-column)
    (4) - Borderline
NumCols is the number of columns for the page.
NumTabs specifies the number of tab settings that follow. You must enter a Type
and Offset for each tab.
Type is the type of tab. The Offset parameter must also be used for each tab.
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
To display leaders preceding the tab, add one of the following values to the
type of tab:
    TabHyph (16384) - Displays dashes
    TabDot (-32768) - Displays dots
    TabLine (-16384) - Displays an underline
Offset is the distance of the tab from the left margin and must be given in
twips (1 inch = 1440 twips). The Type parameter must also be used for each tab.

Return Value
1  (TRUE) if the left footer was modified.
-2  (GeneralFailure) if the left footer was not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage




ΓòÉΓòÉΓòÉ 307. ModLayoutLeftHeader ΓòÉΓòÉΓòÉ

This function modifies the left header information for the current page layout
if the page setting is not for all pages. This function is equivalent to
choosing Page Modify Page Layout, choosing Header, and choosing Left only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutLeftHeader(LeftMargin, TopMargin, RightMargin, BottomMargin, 0, Flag,
NumCols,  NumTabs[, Type, Offset])
LeftMargin is the distance from the left edge of the paper.
TopMargin is the distance from the top edge of the paper.
RightMargin is the distance from the right edge of the paper.
BottomMargin is the distance from the bottom edge of the paper.
The margin parameters are in twips (1 inch = 1440 twips) and represent how much
space to leave on that edge of the paper.
Flag is an options parameter and can have one or more of the following values:
    (1) - Balance (if multi-column)
    (2) - Gutterline (if multi-column)
    (4) - Borderline
NumCols is the number of columns for the page.
NumTabs specifies the number of tab settings that follow. You must enter a Type
and Offset for each tab.
Type is the type of tab. The Offset parameter must also be used for each tab.
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
To display leaders preceding the tab, add one of the following values to the
type of tab:
    TabHyph (16384) - Displays dashes
    TabDot (-32768) - Displays dots
    TabLine (-16384) - Displays an underline
Offset is the distance of the tab from the left margin and must be given in
twips (1 inch = 1440 twips). The Type parameter must also be used for each tab.

Return Value
1  (TRUE) if the left header was modified.
-2  (GeneralFailure) if the left header was not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage




ΓòÉΓòÉΓòÉ 308. ModLayoutLeftLines ΓòÉΓòÉΓòÉ

This function modifies the lines settings for the left page of the current page
layout if the current page layout setting is not for all pages. This function
is equivalent to choosing Page Modify Page Layout, choosing Lines, and choosing
Left only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutLeftLines(GutterShade, GutterStyle, BorderSides, BorderStyle,
BorderSpace)
GutterShade is the color of the lines and can be one of the following:
    White (16777215) - White
    Cyan (16776960) - Light blue
    Yellow (65535) - Yellow
    Magenta (16711935) - Purple
    Green (65280) - Green
    Red (255) - Red
    Blue (16711680) - Blue
    Black (0) - Black
    DarkGray (12566463) - 90% gray scale
    MediumGray (8355711) - 50% gray scale
    LightGray (4144959) - 20% gray scale
    VeryLightGray (1644825) - 10% gray scale
GutterStyle defines the width of the line and can be one of the following:
    Hairline (1) - Hairline
    OnePoint (2) - One point wide
    TwoPoint (3) - Two points wide
    ThreePoint (4) - Three points wide
    FourPoint (5) - Four points wide
    FivePoint (6) - Five points wide
    SixPoint (7) - Six points wide
    DoubleOnePoint (8) - Parallel one point lines
    DoubleTwoPoint (9) - Parallel two point lines
    ThreeLines (10) - Hairline above and below a two point line
    HairBelow (11) - Hairline below a three point line
    HairAbove (12) - Hairline above a three point line
BorderSides is one of the following:
    (1) - All
    (2) - Left
    (4) - Right
    (8) - Top
    (16) - Bottom
    To set a combination of Left, Right, Top, or Bottom, add them together.
BorderStyle is the width of the border from a range of 1 to 12. See GutterStyle
for the values.
BorderSpace is the position of the border with the following values:
    (1) - Middle
    (2) - Inside
    (3) - Outside
    (4) - Close to Inside
    (5) - Close to Outside

Return Value
1  (TRUE) if the left page line settings were modified.
-2  (GeneralFailure) if the left page line settings were not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage


ΓòÉΓòÉΓòÉ 309. ModLayoutLeftPage ΓòÉΓòÉΓòÉ

This function modifies the left page information for the current page layout if
the page setting is not for all pages. This function is equivalent to choosing
Page Modify Page Layout, choosing Margins, and choosing Left only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutLeftPage(LeftMargin, TopMargin, RightMargin, BottomMargin, 0, Flag,
NumCols,  NumTabs[, Type, Offset])
LeftMargin is the distance from the left edge of the paper.
TopMargin is the distance from the top edge of the paper.
RightMargin is the distance from the right edge of the paper.
BottomMargin is the distance from the bottom edge of the paper.
The margin parameters are in twips (1 inch = 1440 twips) and represent how much
space to leave on that edge of the paper.
Flag is an options parameter and can have one or more of the following values:
    (1) - Balance (if multi-column)
    (2) - Gutterline (if multi-column)
    (4) - Borderline
NumCols is the number of columns for the page.
NumTabs specifies the number of tab settings that follow. You must enter a Type
and Offset for each tab.
Type is the type of tab. The Offset parameter must also be used for each tab.
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
To display leaders preceding the tab, add one of the following values to the
type of tab:
    TabHyph (16384) - Displays dashes
    TabDot (-32768) - Displays dots
    TabLine (-16384) - Displays an underline
Offset is the distance of the tab from the left margin and must be given in
twips (1 inch = 1440 twips). The Type parameter must also be used for each tab.

Return Value
1(TRUE) if the left page information was modified.
-2  (GeneralFailure) if the left page information was not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage





ΓòÉΓòÉΓòÉ 310. ModLayoutPageSize ΓòÉΓòÉΓòÉ

This function modifies the page size information for the current page layout.
This function is equivalent to choosing Page Modify Page Layout Page and
choosing Pg. Settings.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutPageSize(Length, Width, 0, 0)
Length is the length of the page in twips (1 inch = 1440 twips), if the paper
type is custom.
Width is the width of the page in twips (1 inch = 1440 twips), if the paper
type is custom.

Return Value
1  (TRUE) if the page size information was modified.
-2  (GeneralFailure) if the page size information was not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage


ΓòÉΓòÉΓòÉ 311. ModLayoutRightFooter ΓòÉΓòÉΓòÉ

This function modifies the footer information for the current page layout if
the page setting is for all or right pages. This function is equivalent to
choosing Page Modify Page Layout, choosing Footer, and choosing All pages or
Right only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutRightFooter(LeftMargin, TopMargin, RightMargin, BottomMargin, 0, Flag,
NumCols,  NumTabs[, Type, Offset])
LeftMargin is the distance from the left edge of the paper.
TopMargin is the distance from the top edge of the paper.
RightMargin is the distance from the right edge of the paper.
BottomMargin is the distance from the bottom edge of the paper.
The margin parameters are in twips (1 inch = 1440 twips) and represent how much
space to leave on that edge of the paper.
Flag is an options parameter and can have one or more of the following values:
    (1) - Balance (if multi-column)
    (2) - Gutterline (if multi-column)
    (4) - Borderline
NumCols is the number of columns for the page.
NumTabs specifies the number of tab settings that follow. You must enter a Type
and Offset for each tab.
Type is the type of tab. The Offset parameter must also be used for each tab.
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
To display leaders preceding the tab, add one of the following values to the
type of tab:
    TabHyph (16384) - Displays dashes
    TabDot (-32768) - Displays dots
    TabLine (-16384) - Displays an underline
Offset is the distance of the tab from the left margin and must be given in
twips (1 inch = 1440 twips). The Type parameter must also be used for each tab.

Return Value
1  (TRUE) if the right footer was modified.
-2  (GeneralFailure) if the right footer was not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage




ΓòÉΓòÉΓòÉ 312. ModLayoutRightHeader ΓòÉΓòÉΓòÉ

This function modifies the header information for the current page layout if
the page setting is for all or right pages. This function is equivalent to
choosing Page Modify Page Layout, choosing Header, and choosing All pages or
Right only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutRightHeader(LeftMargin, TopMargin, RightMargin, BottomMargin, 0, Flag,
NumCols,  NumTabs, Tabs)
LeftMargin is the distance from the left edge of the paper.
TopMargin is the distance from the top edge of the paper.
RightMargin is the distance from the right edge of the paper.
BottomMargin is the distance from the bottom edge of the paper.
The margin parameters are in twips (1 inch = 1440 twips) and represent how much
space to leave on that edge of the paper.
Flag is an options parameter and can have one or more of the following values:
    (1) - Balance (if multi-column)
    (2) - Gutterline (if multi-column)
    (4) - Borderline
NumCols is the number of columns for the page.
NumTabs specifies the number of tab settings that follow. You must enter a Type
and Offset for each tab.
Type is the type of tab. The Offset parameter must also be used for each tab.
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
To display leaders preceding the tab, add one of the following values to the
type of tab:
    TabHyph (16384) - Displays dashes
    TabDot (-32768) - Displays dots
    TabLine (-16384) - Displays an underline
Offset is the distance of the tab from the left margin and must be given in
twips (1 inch = 1440 twips). The Type parameter must also be used for each tab.

Return Value
1  (TRUE) if the right header was modified.
-2  (GeneralFailure) if the right header was not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage



ΓòÉΓòÉΓòÉ 313. ModLayoutRightLines ΓòÉΓòÉΓòÉ

This function modifies the lines settings for the current page layout if the
page setting is for all or right pages. This function is equivalent to choosing
Page Modify Page Layout, choosing Lines, and choosing All pages or Right only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutRightLines(GutterShade, GutterStyle, BorderSides, BorderStyle,
BorderSpace)
GutterShade is the color of the lines and can be one of the following:
    White (16777215) - White
    Cyan (16776960) - Light blue
    Yellow (65535) - Yellow
    Magenta (16711935) - Purple
    Green (65280) - Green
    Red (255) - Red
    Blue (16711680) - Blue
    Black (0) - Black
    DarkGray (12566463) - 90% gray scale
    MediumGray (8355711) - 50% gray scale
    LightGray (4144959) - 20% gray scale
    VeryLightGray (1644825) - 10% gray scale
GutterStyle defines the width of the line and can be one of the following:
    Hairline (1) - Hairline
    OnePoint (2) - One point wide
    TwoPoint (3) - Two points wide
    ThreePoint (4) - Three points wide
    FourPoint (5) - Four points wide
    FivePoint (6) - Five points wide
    SixPoint (7) - Six points wide
    DoubleOnePoint (8) - Parallel one point lines
    DoubleTwoPoint (9) - Parallel two point lines
    ThreeLines (10) - Hairline above and below a two point line
    HairBelow (11) - Hairline below a three point line
    HairAbove (12) - Hairline above a three point line
BorderSides is one of the following:
    (1) - All
    (2) - Left
    (4) - Right
    (8) - Top
    (16) - Bottom
To set a combination of Left, Right, Top, or Bottom, add them together.
BorderStyle is the width of the border from a range of 1 to 12. See GutterStyle
for the values.
BorderSpace is the position of the border with the following values:
    (1) - Middle
    (2) - Inside
    (3) - Outside
    (4) - Close to Inside
    (5) - Close to Outside

Return Value
1  (TRUE) if the right page line settings were modified.
-2  (GeneralFailure) if the right page line settings were not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage


ΓòÉΓòÉΓòÉ 314. ModLayoutRightPage ΓòÉΓòÉΓòÉ

This function modifies the page information for the current page layout if the
page setting is for all or right pages. This function is equivalent to choosing
Page Modify Page Layout, choosing Margins, and choosing All pages or Right
only.


The ModLayoutFinish function must be called after this function to accept the
modifications.

You must call this function after calling the ModLayoutInit function.

Syntax
ModLayoutRightPage(LeftMargin, TopMargin, RightMargin, BottomMargin, 0, Flag,
NumCols,  NumTabs[, Type, Offset])
LeftMargin is the distance from the left edge of the paper.
TopMargin is the distance from the top edge of the paper.
RightMargin is the distance from the right edge of the paper.
BottomMargin is the distance from the bottom edge of the paper.
The margin parameters are in twips (1 inch = 1440 twips) and represent how much
space to leave on that edge of the paper.
Flag is an options parameter and can have one or more of the following values:
    (1) - Balance (if multi-column)
    (2) - Gutterline (if multi-column)
    (4) - Borderline
NumCols is the number of columns for the page.
NumTabs specifies the number of tab settings that follow. You must enter a Type
and Offset for each tab.
Type is the type of tab. The Offset parameter must also be used for each tab.
    TabLeft (1) - Left tab
    TabCenter (2) - Center tab
    TabRight (3) - Right tab
    TabNumeric (4) - Numeric tab
To display leaders preceding the tab, add one of the following values to the
type of tab:
    TabHyph (16384) - Displays dashes
    TabDot (-32768) - Displays dots
    TabLine (-16384) - Displays an underline
Offset is the distance of the tab from the left margin and must be given in
twips (1 inch = 1440 twips). The Type parameter must also be used for each tab.

Return Value
1  (TRUE) if the right page information was modified.
-2  (GeneralFailure) if the right page information was not modified.

Example
FUNCTION Example()
ModLayoutInit(512)
ModLayoutLeftFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutLeftLines(255, 2, 1, 9, 1)
ModLayoutLeftPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutPageSize((11 * 1440), (8.5 * 1440), 0, 0)
ModLayoutRightHeader(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightFooter(1440, 180, 1440, 720, 0, 1, 1, 0)
ModLayoutRightLines(255, 2, 1, 9, 1)
ModLayoutRightPage(1440, 1440, 1440, 1440, 0, 1, 1, 0)
ModLayoutFinish()
END FUNCTION

See also:

    ModLayoutFinish
    ModLayoutInit
    ModLayoutLeftFooter
    ModLayoutLeftHeader
    ModLayoutLeftLines
    ModLayoutLeftPage
    ModLayoutPageSize
    ModLayoutRightFooter
    ModLayoutRightHeader
    ModLayoutRightLines
    ModLayoutRightPage




ΓòÉΓòÉΓòÉ 315. MouseInterrupt ΓòÉΓòÉΓòÉ

This function sets a macro function to be called if the user clicks the mouse
while the current macro is running. This function is passed the window handle
(HWND), a flag, and x and y coordinates.


HWND is the handle of the selected window, and flag is a combination of the
following bits:
    (1) - Left mouse button is down.
    (2) - Right mouse button is down.
    (4) - Shift key is down.
    (8) - Control key is down.

X and Y are relative to upper left corner of HWND and are in device units.

Syntax
MouseInterrupt(Function)
Function is the function that is run when a mouse button is pressed. This
parameter may contain the macro filename or the function within that file to
call.

Return Value
The previously set MouseInterrupt function.

Example
FUNCTION Example()
MouseInterrupt("MouseInt")  ' Set them
TYPE("Click the mouse")
FOR i = 1 to 5  ' Kill some time.
    FOR j = 1 to 100
    NEXT
    TYPE("{i}.")
NEXT
END FUNCTION

' The Interrupt function: just echo the input parameters

FUNCTION MouseInt(hwnd, flag, x, y)
Message("hwnd {hwnd}, flag {flag}, {x}, {y}")
END FUNCTION

See Also:

    DlgKeyInterrupt
    KeyInterrupt




ΓòÉΓòÉΓòÉ 316. New ΓòÉΓòÉΓòÉ

This function displays the New dialog box. This function is equivalent to
choosing File New.


Syntax
New(Style, WithContents, Options)
Style is the style sheet file to use with the new file.
WithContents determines if the new file is created with the paragraph style
sheet contents. It can be one of the following:
    NoContents (0) - Do not bring in contents of paragraph style sheet
    WithContents (1) - Bring in contents with paragraph style sheet
Options determines if the new file is placed in a new window or replaces the
currently active document. It can be one of the following values:
    (0) - Open another window for the new file
    (128) - Close the current document
    (512) - Do not run the macro associated with the style sheet, if one exists
    (1024) - Show the style sheets by description rather than file name when
    the New dialog box displays
If the ReplaceCurrent option is used and a document is already open, then the
new file replaces the current document in the selected window. If the
ReplaceCurrent option is set, then any documents opened thereafter have this
option set.

To display the New dialog box and allow the user to choose the style sheet file
and with contents options: New

Return Value
1  (TRUE) if the new file was created.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the file was not created.

Example
FUNCTION Example()
New("_MACRO.STY", 1, 0)
END FUNCTION
See also:  FileOpen
    GetOpenFileName$




ΓòÉΓòÉΓòÉ 317. NewWindow ΓòÉΓòÉΓòÉ

This function creates a new window with the same name as the active window.
This function is equivalent to choosing Window New Window.


Syntax
NewWindow()

Return Value
1  (TRUE) if the new window was created.
-2  (GeneralFailure) if the new window was not created.

Example
FUNCTION Example()
thisfile = GetOpenFileName$()
Message("Opening another window for {thisfile}.")
NewWindow()
END FUNCTION

See also:

    CascadeWindow
    NextWindow
    SelectWindow
    TileWindow


ΓòÉΓòÉΓòÉ 318. NextWindow ΓòÉΓòÉΓòÉ

This function changes the active document window to the next document window.
This function is equivalent to pressing CTRL+TAB.


Syntax
NextWindow()

Return Value
This function does not return a value.

Example
FUNCTION Example()
NextWindow()
END FUNCTION

See also:

    CascadeWindow
    NewWindow
    SelectWindow
    TileWindow



ΓòÉΓòÉΓòÉ 319. NoHyphenation ΓòÉΓòÉΓòÉ

This function sets the no hyphenation attribute for selected text or for all
following text if no text is selected. It acts as a toggle, turning off the
attribute if it is currently on or turning on the attribute if it is currently
off. This function is equivalent to choosing Edit Mark Text No Hyphenation.


Syntax
NoHyphenation()

Return Value
1  (TRUE) if the change of hyphenation was successful.
-2  (GeneralFailure) if the change of hyphenation was not successful.

Example
FUNCTION Example()
NoHyphenation()
END FUNCTION

See also:

    SetDefOptions


ΓòÉΓòÉΓòÉ 320. NormalText ΓòÉΓòÉΓòÉ

This function removes attributes for selected text or for all following text if
no text is selected. This function is equivalent to choosing Text Normal.


Syntax
NormalText()

Return Value
1(TRUE) if the attributes were removed from the text.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
String = "This is a line of text."
Bold(1)
Italic(1)
TYPE("{String}")
NormalText()
TYPE("{String}")
END FUNCTION

See also:

    Bold
    Italic
    Underline
    WordUnderline


ΓòÉΓòÉΓòÉ 321. Notes ΓòÉΓòÉΓòÉ

This function opens a note located at the insertion point and allows the user
to edit it. It is the equivalent of double-clicking on a note. This function
does not automatically insert or delete notes.


To set the user initials for notes and the default note color, use the
UserSetup function.

Syntax
Notes()

Return Value
1  (TRUE) if the notes function was completed.
-2  (GeneralFailure) if the notes function was not completed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
Notes()
END FUNCTION

See also:

    InsertNote
    UserSetUp


ΓòÉΓòÉΓòÉ 322. Now ΓòÉΓòÉΓòÉ

This function returns the number of seconds that have elapsed since midnight on
January 1, 1970.


Syntax
Now()

Return Value
A number corresponding to the number of seconds that have elapsed since
midnight on January 1, 1970.

Example
FUNCTION Example()
Born = Query$("What is your Birthday (MM/DD/YYYY)?")
Date = FormatDate$(Now(), "h")
Time = FormatTime$(Now(), 6)
Days = DateDiff(Born, Date)
TextDate = FormatDate$(Now(), "d")
Message("It is now {Time} on {TextDate}. You are {Days} days old.")
END FUNCTION

See also:

    FormatDate$
    FormatTime$
    GetTime
    InsertDate



ΓòÉΓòÉΓòÉ 323. OnKey ΓòÉΓòÉΓòÉ

This function sets an accelerator key when you specify an Ami Pro function or a
macro name. Any accelerator key currently set to the specified keystroke is
reassigned to the new function or macro. This function is equivalent to
choosing Tools Macros Edit and then entering keys in the Shortcut keys text
box.


Syntax
OnKey(Key, Function, MacroName)
Key is the keystroke, enclosed in square brackets, to use as an accelerator
key, in square brackets.
You can use either CTRL or SHIFT, or a combination of the two, with most keys.
When assigning a shortcut, you must spell out the shortcut command keys. For
example, to assign SHIFT+F2, you must type the actual alphanumeric characters
with no spaces. You cannot use F10, SHIFT+F1, or SHIFT+ an alphanumeric key.
Function is the Ami Pro function this keystroke should execute. If a macro is
to be run, this parameter should be the null string(""). Do not include
parentheses around the function.
MacroName is the name of the macro to be run. If an Ami Pro function is to be
executed, this parameter should be the null string ("").
To reassign the keystroke to its original state, set Function equal to 0 and
set MacroName equal to the null string ("").

Return Value
Non zero number (TRUE) if the accelerator key was assigned.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the accelerator key could not be assigned.

Example
FUNCTION Example()
OnKey([ctrlshifts], SaveAs, "")
END FUNCTION

See also:

    ChangeShortcutKey




ΓòÉΓòÉΓòÉ 324. OpenDataFile ΓòÉΓòÉΓòÉ

This function opens a merge data file. It does not edit the data file
automatically.


Syntax
OpenDataFile(FileName, App)
FileName is the name of the document to open. If the file to be opened is not
in the current directory or document directory, the full path must be used.
App is the Ami Pro file type. To open an Ami Pro file, use the null string
("").

Return Value
This function returns 1.

Example
FUNCTION Example()
OpenDataFile("senators.sam","")
END FUNCTION

See also:

    CreateDataFile
    MergeToFile
    OpenMergeFile





ΓòÉΓòÉΓòÉ 325. OpenMergeFile ΓòÉΓòÉΓòÉ

This function opens a merge document file. The user can insert additional field
names into the document, continue the merge, or select a data file.


Syntax
OpenMergeFile(FileName, Options, App)
FileName is the name of the document to open. If the file to be opened is not
in the current directory or document directory, the full path must be used. To
open the 'Untitled' file, use the null string ("") as the file name.
Options is a number corresponding to the options for the file you open. To use
both options, add them together.
    (1) - Required
    (128) - Close the current file (must combine with 1)
App is the Ami Pro file type. To open an Ami Pro file, use the null string
("").

Return Value
This function returns 1.

Example
FUNCTION Example()
OpenMergeFile("Merge.sam", 1, "")
END FUNCTION

See also:

    CreateDataFile
    MergeToFile
    OpenDataFile




ΓòÉΓòÉΓòÉ 326. OpenPreviousFile ΓòÉΓòÉΓòÉ

These functions open one of the last five previously opened Ami Pro files. The
function OpenPreviousFile1 is the most recently opened file and
OpenPreviousFile5 is the oldest file. Choosing these functions are equivalent
to choosing File/#, where # is the number to the left of the file name to open
at the bottom of the File menu.


The number of recently open files to display may be set using the UserSetup
function.

Syntax
OpenPreviousFile1()
OpenPreviousFile2()
OpenPreviousFile3()
OpenPreviousFile4()
OpenPreviousFile5()

Return Value
0 (FALSE) if the user cancels the function or if no action is taken.
1 (TRUE) if the file is opened.
-2 (GeneralFailure) if the file is not opened.

Example
FUNCTION Example()
OpenPreviousFile1()
END FUNCTION

See also:

    UserSetup


ΓòÉΓòÉΓòÉ 327. OutlineLevels ΓòÉΓòÉΓòÉ

This function changes the number of displayed outline levels. The number of
levels set are the number of levels printed if the document is printed. This
function is equivalent to clicking the icon for the number of outline levels
while in Outline Mode.


You must be in Outline Mode to use this function.

Syntax
OutlineLevels(Levels)
Levels is the number of outline levels to display.

Return Value
This function returns 1.

Example
FUNCTION Example()
Levels = Query$("Levels?")
OutlineLevels(Levels)
END FUNCTION

See also:

    OutlineMode
    OutlineStyle



ΓòÉΓòÉΓòÉ 328. OutlineMode ΓòÉΓòÉΓòÉ

This function changes the current document in Ami Pro from Draft Mode or Layout
Mode to Outline Mode. This function is equivalent to choosing View Outline
Mode.


Syntax
OutlineMode()

Return Value
1  (TRUE) if the view mode was changed.
0  (NoAction) if no action was taken because Ami Pro is already in the mode
selected.

Example
FUNCTION Example()
OutlineMode()
END FUNCTION

See also:

    DraftMode
    EnlargedView
    FacingView
    FullPageView
    GetMode
    GetViewLevel
    LayoutMode
    OutlineMode
    StandardView





ΓòÉΓòÉΓòÉ 329. OutlineStyle ΓòÉΓòÉΓòÉ

This function assigns outline styles and options to paragraph styles. This
function is equivalent to choosing Style Outline Styles.


Syntax
OutlineStyle(Count[, Style, Level, Options, BulletText])
Count is the number of levels to which you assign styles.
The remaining parameters depend on Count. An entire set of the optional
parameters must be present for the number of levels defined by the Count
parameter.
Style is the paragraph to which you want to assign a style.
Level is the outline level in which the style is assigned.
Options is the reset options for each outline level. It is one of the following
values:
    (0) - Do not reset
    (2) - Reset after a higher level
    (4) - Reset after an intervening style
    (8) - Turn on cumulative numbering
The Reset after a higher level and Reset after an intervening style options
cannot be used together. However, the cumulative numbering value can be
combined with either of the other values.
BulletText is the leading text for the paragraph. The BulletText parameter
specifies the text, bullets, or numbers which must precede each paragraph using
this paragraph style. The text must be typed as it would appear in the edit box
in the Style Modify Style Bullets & numbers dialog box. Bullets can be inserted
by typing the following text where the bullet should be placed:
    <Γòû1> - Small  Round Bullet
    <Γòû2> - Large  Round Bullet
    <Γòû3> - Small  Square Bullet
    <Γòû4> - Large  Square Bullet
    <Γòû5> - Large  Outline Square Bullet
    <Γòû6> - Small  Diamond Bullet
    <Γòû7> - Large  Diamond Bullet
    <Γòû8> - Small  Open Circle Bullet
    <Γòû9> - Large  Open Circle Bullet
    <Γòû10> - Check  Mark
    <Γòû11> - Tack
    <Γòû12> - Square shadow below bullet
    <Γòû13> - Square shadow above bullet
    <Γòû14> - Check box
    <Γòû15> - Square with X bullet
    <Γòû16> - Rounded arrowhead top shaded
    <Γòû17> - Rounded arrowhead bottom shaded
To type the dot in front of the bullet number, turn on Num Lock, hold the ALT
key, and type 0183, and release the ALT key.

Numbers can be inserted by typing the following text where the number should be
inserted:
    <#1> - 1 2 3 4 5...
    <#2> - A B C D E...
    <#3> - a b c d e...
    <#4> - I II III IV V...
    <#5> - i ii iii iv v...
    <#6> - * ** *** ****...

Return Value
1  (TRUE) if the outline style is created.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
OutlineStyle(1, "Body Text", 1, 4, "<Γòû17>")
END FUNCTION

See also:

    ModifyStyle
    OutlineLevels
    OutlineMode





ΓòÉΓòÉΓòÉ 330. PageBreak ΓòÉΓòÉΓòÉ

This function inserts or removes a page break at the insertion point. This
function is equivalent to choosing Page Breaks.


Syntax
PageBreak(Function)
Function is the page break function desired. The Function parameter defines the
page break function to use, according to the following list:
    InsBreak (1) - Insert page break
    DelBreak (2) - Remove page break
    CenterBreak (3) - Vertically center text above page break
    InsColBreak (4) - Insert column break
    DelColBreak (5) - Remove column break

To display the Page Breaks dialog box and allow the user to choose the page
break options: PageBreak

Return Value
1  (TRUE) if the page break was inserted or removed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the break was not inserted or removed.

Example
FUNCTION Example()
PageBreak(1)
END FUNCTION

See also:

    InsertLayout


ΓòÉΓòÉΓòÉ 331. PageNumber ΓòÉΓòÉΓòÉ

This function is equivalent to choosing Page Page Numbering.


Syntax
PageNumber(Text, StartOn, StartNum, Style)
Text is the leading text to use for the page number. If no leading text is
used, this parameter should be the null string ("").
StartOn is the page number to start the numbering on.
StartNum is the number to use for the first numbered page.
Style is the numbering style to use for the number and can be one of the
following:
    (1) - 1, 2, 3, 4, 5
    (I) - I, II, III, IV, V, VI
    (i) - i, ii, iii, iv, v, vi
    (A) - A, B, C, D, E, F
    (a) - a, b, c, d, e, f

To display the Page Numbering dialog box and allow the user to choose the page
number: PageNumber

Return Value
1  (TRUE) if the page number was inserted.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the number was not inserted.

Example
FUNCTION Example()
PageNumber("Page", 1, 1, 1)
END FUNCTION

See also:

    LineNumber


ΓòÉΓòÉΓòÉ 332. Paste ΓòÉΓòÉΓòÉ

This function pastes the contents of the clipboard at the location of the
insertion point. This function is equivalent to choosing Edit Paste.


Syntax
Paste()

Return Value
1  (TRUE) if the text was pasted.
-2  (GeneralFailure) if the text could not be pasted or if there was no text to
paste.

Example
FUNCTION Example()
Stuff = Query$("Enter what you want put on the clipboard:")
ClipboardWrite(Stuff, 1)
CALL Example2()
END FUNCTION

FUNCTION Example2()
Paste()
TYPE("[Enter]Should look exactly like the line below:[Enter]")
TYPE(ClipboardRead(1))
END FUNCTION

See also:

    Copy
    CurChar$
    CurShade$
    CurWord$
    Cut


ΓòÉΓòÉΓòÉ 333. Pause ΓòÉΓòÉΓòÉ

This function allows the macro to pause for a set period of time before
continuing.


Syntax
Pause(Time)
Time is the amount of time to pause, in tenths of seconds.

Return Value
This function does not return a value.

Example
FUNCTION Example()
TYPE("Hello...")
PAUSE(030)
TYPE("There!")
END FUNCTION

See also:

    GetTime
    HourGlass
    RunLater


ΓòÉΓòÉΓòÉ 334. PhysicalToLogical ΓòÉΓòÉΓòÉ

This function returns the logical page number in a master document, given the
physical page number.


Syntax
PhysicalToLogical(Page)
Page is the page number that appears when the file is opened for viewing.

Return Value
The logical page number (the number that actually prints in a master document
print).
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
Count = GetBookMarkCount()
IF Count > 0
    DIM Bookmarks(Count)
    GetBookMarkNames(&Bookmarks)
    DeleteMenu(1, "&Bookmarks")
    AddMenu(1, "&Bookmarks")
    FOR I = 1 to Count
       ThisBookmark = Bookmarks(I)
       AddMenuItem(1, "&Bookmarks", ThisBookmark, "{MacFile}!Example2(
 {ThisBookmark})", ThisBookmark)
    NEXT
ELSE
    Message("No bookmarks in this document!")
ENDIF
END FUNCTION

FUNCTION Example2(Bkmk)
MarkBookMark(Bkmk, FindBookmark)
PhysicalPage = GetBookMarkPage(Bkmk)
LogicalPage = PhysicalToLogical(GetBookMarkPage(Bkmk))
Message("{Bkmk} is on physical page {PhysicalPage} and logical page
{LogicalPage}.")
END FUNCTION

See also:

    GetBookMarkPage
    GetFmtPageStr$


ΓòÉΓòÉΓòÉ 335. PrintEnvelope ΓòÉΓòÉΓòÉ

This function displays the Print Envelope dialog box. This function does not
automatically print the envelope. This function is equivalent to choosing File
Print Envelope.


Syntax
PrintEnvelope()

Return Value
This function returns 1.

Example
FUNCTION Example()
PrintEnvelope()
END FUNCTION

See also:

    FilePrint
    PrintSetup


ΓòÉΓòÉΓòÉ 336. PrintOptions ΓòÉΓòÉΓòÉ

This function sets print options to use for print and merge. If this function
is not used before printing and merging, the default options are used for
printing the document. This function is equivalent to choosing File Print and
choosing Options.


Syntax
PrintOptions(Flag, 0, 0)
Flag is a number that defines the value of other print options and may be one
or more of the following:
    Reverse (2) - Prints the document in reverse order.
    Collate (4) - Collate multiple copy output.
    CropMarks (16) - Print the document with crop marks.
    PrePrinted (64) - Print the document on preprinted forms.
    PrintUpdateFields (128) - Updates power fields before printing.
    PrintNoPictures (2048) - Prints the document without pictures. To print
    with pictures do not use this value.
The desired options should be added together to make up the value of the  flag
parameter.

To display the Merge dialog box and allow the user to set print options for
merge: Merge

To display the Print dialog box and allow the user to set print options for
print: FilePrint

Return Value
1  (TRUE) if the print options were set.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the print options were not set.

Example
FUNCTION Example()
'print crop marks
PrintOptions(16, 0, 0)
FilePrint(1, 1, 9999, 1)
END FUNCTION

See also:

    FilePrint
    Merge
    MergeMacro
    MergeToFile


ΓòÉΓòÉΓòÉ 337. PrintSetup ΓòÉΓòÉΓòÉ

This function selects a new printer and printer port for the current document.
This function is equivalent to choosing File Printer Setup.


Syntax
PrintSetup(Printer, Port)
Printer is the name of the printer that must be used for this document.
Port is the name of the port to which the printer is attached.

To display the Printer Setup dialog box and allow the user to select the name
of the printer to use or to allow the printer to be configured: PrintSetup

Return Value
1  (TRUE) if the named printer was successfully selected for the document.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the printer name was incorrect.

Example
FUNCTION Example()
PrintSetup("Apple LaserWriter II NTX", "LPT1:")
Message("Printer changed to LaserWriter on LPT1")
END FUNCTION

See also:

    FilePrint


ΓòÉΓòÉΓòÉ 338. ProtectCells ΓòÉΓòÉΓòÉ

This function sets protection of the selected table cells. It acts as a toggle,
turning off the protection if it is currently on or turning on the protection
if it is currently off. This function is equivalent to choosing Table Protect
Cells.


The insert point must be in a table to use this function.

Syntax
ProtectCells([on])
On is an optional parameter that turns protection on.
Return Value
1  (TRUE) if the cells were protected or unprotected.
-2  (GeneralFailure) if the cells could not be protected or unprotected or if
the program was not in  tables mode.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
ProtectCells()
END FUNCTION

See also:

    ConnectCells
    TableLayout
    Tables


ΓòÉΓòÉΓòÉ 339. Query ΓòÉΓòÉΓòÉ

This function displays a message box with a specified prompt, an edit box for
the user to enter string data to be sent back to the macro, and OK and Cancel
buttons. You can use Query$ to request information from the user.


Syntax
Query$(Prompt[, Text])
Prompt is a string passed as a prompt to the user. Ami Pro accepts a maximum of
80 characters. However, the number of characters that actually display depends
on the font used for dialog boxes.
Text is an optional parameter that displays in the edit box as a default.

Return Value
The string typed by the user.
Null string ("") if the user does not type anything.
If the user chooses Cancel instead of OK, the macro executes the ONCANCEL
routine (if one has been defined).

Example
FUNCTION Example()
name = Query$("What is your name?", "Cassie")
Message("Hi, {name}")
END FUNCTION

See also:

    Decide
    DialogBox
    Message
    Using the ONCANCEL Statement
    UserControl



ΓòÉΓòÉΓòÉ 340. QuickAddCol ΓòÉΓòÉΓòÉ

This function sums a column and places the results in the current cell. This
function is equivalent to choosing Table Quick Add Column.


Syntax
QuickAddCol()

Return Value
1  (TRUE) if the column was added.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
Message("Adding the current column of numbers")
QuickAddCol()
END FUNCTION

See also:

    SetFormula
    EditFormula
    QuickAddRow



ΓòÉΓòÉΓòÉ 341. QuickAddRow ΓòÉΓòÉΓòÉ

This function sums a row and places the results in the current cell. This
function is equivalent to choosing Table Quick Add Row.


Syntax
QuickAddRow()

Return Value
1  (TRUE) if the row was added.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
Message("Adding the current row of numbers")
QuickAddRow()
END FUNCTION

See also:

    EditFormula
    QuickAddCol
    SetFormula



ΓòÉΓòÉΓòÉ 342. ReadMail ΓòÉΓòÉΓòÉ

This function allows you to view any messages that have been received. This
function is equivalent to clicking the mail button on the status bar (to the
left of the Insert Type Rev button). If the mail server is running, the server
is activated so you can view the mail that has been received.


This function is only available if Lotus Notes is installed.

Syntax
ReadMail()

Return Value
1  (TRUE) if the mail server was activated to view the mail.
0  (NoAction) if the mail server was not running or if there is no mail.

Example
FUNCTION Example()
result = ReadMail()
IF result = 0
    Message("No mail.")
ENDIF
END FUNCTION

See also:

    SendMail



ΓòÉΓòÉΓòÉ 343. RecClose ΓòÉΓòÉΓòÉ

This function closes the data file that was opened by the RecOpen function.
This data file is in memory.


Syntax
RecClose(Handle)
Handle is the file ID handle returned by the RecOpen function.

Return Value
1  (TRUE) if the data file was closed.
-2  (GeneralFailure) if the data file could not be closed.

Example
FUNCTION Example()
DIM field(12)
handle = RecOpen("DATAFILE.SAM", "")
Message(handle)
IF handle THEN
    numfields = RecFieldCount(handle)
    Message("There are {numfields} fields:")
    IF numfields>12 THEN
       Message("Warning - Cannot display all fields")
       numfields=12
    ENDIF
    FOR I = 1 to numfields
       name=(RecFieldName$(handle, I))
       Message("Field name = {name}")
       field(i)=name
    NEXT
    WHILE RecNextRec(handle)=0
       FOR i=1 TO numfields
           name=(RecGetField(handle, field(i)))
           Message("Field value = {name}")
       NEXT
    WEND
    RecClose(handle)
ELSE
    Message("Could not open document")
ENDIF
END FUNCTION

See also:

    RecFieldCount
    RecFieldName$
    RecGetField
    RecNextRec
    RecOpen


ΓòÉΓòÉΓòÉ 344. RecFieldCount ΓòÉΓòÉΓòÉ

This function counts the number of fields in the specified data file. This data
file is in memory.


Syntax
RecFieldCount(Handle)
Handle is the file ID handle returned by the RecOpen function.

Return Value
The number of fields in the data file.
-2  (GeneralFailure) if the number of fields could not be determined.

Example
FUNCTION Example()
DIM field(12)
handle = RecOpen("DATAFILE.SAM", "")
Message(handle)
IF handle THEN
    numfields = RecFieldCount(handle)
    Message("There are {numfields} fields:")
    IF numfields>12 THEN
       Message("Warning - Cannot display all fields")
       numfields=12
    ENDIF
    FOR I = 1 to numfields
       name=(RecFieldName$(handle, I))
       Message("Field name = {name}")
       field(i)=name
    NEXT
    WHILE RecNextRec(handle)=0
       FOR i=1 TO numfields
           name=(RecGetField(handle, field(i)))
           Message("Field value = {name}")
       NEXT
    WEND
    RecClose(handle)
ELSE
    Message("Could not open document")
ENDIF
END FUNCTION

See also:

    RecClose
    RecFieldName$
    RecGetField
    RecNextRec
    RecOpen


ΓòÉΓòÉΓòÉ 345. RecFieldName ΓòÉΓòÉΓòÉ

This function retrieves the name of the field for the specified field number.
The name is retrieved from the data file in memory.


Syntax
RecFieldName$(Handle, FieldNumber)
Handle is the file ID handle returned by the RecOpen function.
FieldNumber is the number of the field name to retrieve from the field names
paragraph in the data file.

Return Value
A string containing the requested field name.
-2  (GeneralFailure) if the field name could not be extracted.

Example
FUNCTION Example()
DIM field(12)
handle = RecOpen("DATAFILE.SAM", "")
Message(handle)
IF handle THEN
    numfields = RecFieldCount(handle)
    Message("There are {numfields} fields:")
    IF numfields>12 THEN
       Message("Warning - Cannot display all fields")
       numfields=12
    ENDIF
    FOR I = 1 to numfields
       name=(RecFieldName$(handle, I))
       Message("Field name = {name}")
       field(i)=name
    NEXT
    WHILE RecNextRec(handle)=0
       FOR i=1 TO numfields
           name=(RecGetField(handle, field(i)))
           Message("Field value = {name}")
       NEXT
    WEND
    RecClose(handle)
ELSE
    Message("Could not open document")
ENDIF
END FUNCTION

See also:

    RecClose
    RecFieldCount
    RecGetField
    RecNextRec
    RecOpen


ΓòÉΓòÉΓòÉ 346. RecGetField ΓòÉΓòÉΓòÉ

This function retrieves the contents of the specified field in the current
record. The name is retrieved from the data file in memory.


Syntax
RecGetField(Handle, "FieldName")
Handle is the file ID handle returned by the RecOpen function.
FieldName is the name of the field to retrieve from the current record in the
data file.

Return Value
The contents of the specified field.
-2  (GeneralFailure) if the contents could not be retrieved.

Example
FUNCTION Example()
DIM field(12)
handle = RecOpen("DATAFILE.SAM", "")
Message(handle)
IF handle THEN
    numfields = RecFieldCount(handle)
    Message("There are {numfields} fields:")
    IF numfields>12 THEN
       Message("Warning - Cannot display all fields")
       numfields=12
    ENDIF
    FOR I = 1 to numfields
       name=(RecFieldName$(handle, I))
       Message("Field name = {name}")
       field(i)=name
    NEXT
    WHILE RecNextRec(handle)=0
       FOR i=1 TO numfields
           name=(RecGetField(handle, field(i)))
           Message("Field value = {name}")
       NEXT
    WEND
    RecClose(handle)
ELSE
    Message("Could not open document")
ENDIF
END FUNCTION

See also:

    RecClose
    RecFieldCount
    RecFieldName$
    RecNextRec
    RecOpen


ΓòÉΓòÉΓòÉ 347. RecNextRec ΓòÉΓòÉΓòÉ

This function advances the record pointer to the next record in the specified
data file. This data file is in memory.


Syntax
RecNextRec(Handle)
Handle is the file ID handle returned by the RecOpen function.

Return Value
0  if the action was successful.
-1  if the end of the file was reached.

Example
FUNCTION Example()
DIM field(12)
handle = RecOpen("DATAFILE.SAM", "")
Message(handle)
IF handle THEN
    numfields = RecFieldCount(handle)
    Message("There are {numfields} fields:")
    IF numfields>12 THEN
       Message("Warning - Cannot display all fields")
       numfields=12
    ENDIF
    FOR I = 1 to numfields
       name=(RecFieldName$(handle, I))
       Message("Field name = {name}")
       field(i)=name
    NEXT
    WHILE RecNextRec(handle)=0
       FOR i=1 TO numfields
           name=(RecGetField(handle, field(i)))
           Message("Field value = {name}")
       NEXT
    WEND
    RecClose(handle)
ELSE
    Message("Could not open document")
ENDIF
END FUNCTION

See also:

    RecClose
    RecFieldCount
    RecFieldName$
    RecGetField
    RecOpen


ΓòÉΓòÉΓòÉ 348. RecOpen ΓòÉΓòÉΓòÉ

This function allows you to open an existing data file.


Syntax
RecOpen(FileName, Description[, Options])
FileName is the name of the data file to open. You must include the full path
as well as the file name.
Description is the description file. If the data file is an Ami Pro document,
the description is the null string ("").
Options is the filter type when import filters are used to read the data file.

Return Value
A positive number if the record is opened.
0  (FALSE) if the record is not opened.

Example
FUNCTION Example()
DIM field(12)
handle = RecOpen("DATAFILE.SAM", "")
Message(handle)
IF handle THEN
    numfields = RecFieldCount(handle)
    Message("There are {numfields} fields:")
    IF numfields>12 THEN
       Message("Warning - Cannot display all fields")
       numfields=12
    ENDIF
    FOR I = 1 to numfields
       name=(RecFieldName$(handle, I))
       Message("Field name = {name}")
       field(i)=name
    NEXT
    WHILE RecNextRec(handle)=0
       FOR i=1 TO numfields
           name=(RecGetField(handle, field(i)))
           Message("Field value = {name}")
       NEXT
    WEND
    RecClose(handle)
ELSE
    Message("Could not open document")
ENDIF
END FUNCTION

See also:

    RecClose
    RecFieldCount
    RecFieldName$
    RecGetField
    RecNextRec



ΓòÉΓòÉΓòÉ 349. RemoveLayout ΓòÉΓòÉΓòÉ

This function deletes the page layout for the current page. The page layout for
the previous page is effective for the current page. If the page layout deleted
was for the first page, the original (default) page layout is in effect. This
function is equivalent to choosing Page Insert Page Layout Remove.


You must be in Layout Mode to use this function.

Syntax
RemoveLayout()

Return Value
1  (TRUE) if the page layout was deleted.
-2  if the page layout was not deleted.
0  (NoAction) if no action was taken.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
choice = Decide("This will remove the current page layout. Continue?")
IF choice = 1
  RemoveLayout()
ENDIF
END FUNCTION

See also:

    InsertLayout
    RevertLayout


ΓòÉΓòÉΓòÉ 350. RenameDocInfoField ΓòÉΓòÉΓòÉ

This function renames the eight user defined document information fields. This
function is equivalent to choosing File Doc Info, selecting Fields, and then
selecting Rename Fields.


Syntax
RenameDocInfoField(FieldNumber, Field)
FieldNumber is the number of the field to rename. The first field number is 0.
Field is the new name for the field.

To display the Document Info dialog box and allow the user to choose names for
the fields: DocInfo

Return Value
1  (TRUE) if the new document info field name was saved.
-2  (GeneralFailure) if the name was not saved.

Example
FUNCTION Example()
FieldNum = Query$("What field do you want to rename?")
FieldName = Query$("What do you want to rename field #{FieldNum} to?")
RenameDocInfoField(FieldNum, FieldName)
END FUNCTION

See also:

    DocInfo
    InsertDocInfo


ΓòÉΓòÉΓòÉ 351. RenameMenuItem ΓòÉΓòÉΓòÉ

This function gives a new name to an existing menu item. RenameMenuItem does
not change the functionality of the menu item, but simply gives it a new name.
The new name displays the next time the user displays the pulldown menu.


Syntax
RenameMenuItem(BarID, Menu[, CascadeMenu], OldName, NewName)
BarID is the identification number of the menu bar and must always be 1.
Menu is the name of the pull down menu that contains the item you wish to
rename. This must match exactly the name of the pull down menu you want to
modify, including ampersand (&) characters. An ampersand is placed before a
character that has an underline.
CascadeMenu is the optional Cascade menu name that contains the item you wish
to rename. This must match exactly the name of the cascade menu you want to
modify, including ampersand (&) characters.
OldName is the current name of the menu item.
NewName is the new name to use for the menu item.

Return Value
1  (TRUE) if the item was successfully renamed.
0  (FALSE) if the item could not be found.

Example
FUNCTION Example()
RenameMenuItem(1, "&File", "E&xit", "&Quit")
END FUNCTION

See also:

    AddMenu
    AddMenuItem
    ChangeMenuAction
    CheckMenuItem
    DeleteMenu
    DeleteMenuItem
    GrayMenuItem




ΓòÉΓòÉΓòÉ 352. Replace ΓòÉΓòÉΓòÉ

This function finds and optionally replaces text or paragraph styles in a
document. This function is equivalent to choosing Edit Find & Replace. If the
macro replaces all the occurrences of a phrase or paragraph style, the macro
works as if the user initiated Find & Replace and issued the Replace All
command. If the ReplaceAll flag is not used, this function finds the first
occurrence of the target phrase and continues with the macro. If the ReplaceAll
flag is not used, this function does not perform a replacement.


The Replace function is not interactive. If an interactive Find & Replace is
desired, use the FindReplace function.

A macro must be edited to insert this non-recordable function.

Syntax
Replace(SourceAttr, DestAttr, Flag, FindString, ReplaceString)
SourceAttr is the attribute combination for the source string and can be one or
more of the following:
    NormalAttr (0) - Text without any attributes
    BoldText (4) - Bold  Text
    ItalicText (8) - Italicized text
    UnderlineText (16) - Underlined text
    WordUnderlineText (32) - Word underlined text
    SmallCaps (-32768) - Small caps text
Multiple attributes can be specified by adding the SourceAttr values together.
DestAttr is the attribute combination for the destination string and can be one
or more of the following:
    NormalAttr (0) - Text without any attributes
    BoldText (4) - Bold  Text
    ItalicText (8) - Italicized text
    UnderlineText (16) - Underlined text
    WordUnderlineText (32) - Word underlined text
    SmallCaps (-32768) - Small caps text
Multiple attributes can be specified by adding the DestAttr values together.
Flag is a flag that defines the options for the Find & Replace and can be one
or more of the following:
    FindExact (1) - Find only text with same capitalization as typed in search
    string
    FindStyles (2) - Find/replace paragraph styles instead of text
    FindWholeWord (4) - Find only whole words
    FindBackwards (8) - Find from the current cursor position to the beginning
    of the document
    ReplaceExact (16) - Replace using capitalization specified for replace
    string
    ReplaceExactAttr (32) - Replace using attributes specified, rather than as
    found
    FindExactAttr (64) - Find only text with same attributes as specified
    ReplaceAll (1024) - Replace all occurrences without stopping for
    confirmation. If the ReplaceAll flag is not used, this function does not
    perform a replacement.
    FindFromPage1 (8192) - Start search on page 1 of document
    FindCurrentStream (16384) - Find only in the current text stream
    Note: Setting this option turns off the option to search in other text
    streams, unlike the other flags, which turn on the option.
Multiple options can be specified by adding values together.
FindString is the string or paragraph style to search for.
ReplaceString is the string or paragraph style name to replace with. If the
ReplaceAll flag is not used, this parameter is ignored.

To display the Find/Replace dialog box and allow the user to determine the
parameters for the find and replace operation: FindReplace

Return Value
1  (TRUE) if the find/replace function was successful.
-7  (EndFile) if the end of the file was reached or if no match was found.
Since a global replacement always reaches the end of the file, this function
always returns EndFile if the ReplaceAll option is used.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
Message("Replacing a's with x's")
Replace(0, 0, 0, "a", "x")
END FUNCTION

See also:

    FindReplace
    GoToCmd




ΓòÉΓòÉΓòÉ 353. Restore ΓòÉΓòÉΓòÉ

This function restores the Ami Pro window to the size of the last non-full
screen window. This function is equivalent to choosing System Restore.


Syntax
Restore()

Return Value
This function does not return a value.

Example
FUNCTION Example()
Restore()
END FUNCTION

See also:

    Maximize
    Minimize


ΓòÉΓòÉΓòÉ 354. Revert ΓòÉΓòÉΓòÉ

This function cancels changes made to the document since it was last saved and
displays the previously saved version of the document. This function is
equivalent to choosing File Revert to Saved.


Normally, the user is given a chance to abort the revert. If you want to avoid
this message in your macro, use the Messages function to turn off messages
before using this function.

Syntax
Revert()

Return Value
1  (TRUE) if the file successfully reverted to the previous version.
-2  (GeneralFailure) if the file could not be reverted.

Example
FUNCTION Example()
Revert()
END FUNCTION

See also:

    Messages
    SaveAs
    Save


ΓòÉΓòÉΓòÉ 355. RevertLayout ΓòÉΓòÉΓòÉ

You can use RevertLayout to insert a page layout that uses the settings in
effect for the first page of the document. This function is equivalent to
choosing Page Insert Page Layout Revert.


Syntax
RevertLayout()

Return Value
1  (TRUE) if the page layout was successfully reverted.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
RevertLayout()
END FUNCTION

See also:

    InsertLayout
    RemoveLayout


ΓòÉΓòÉΓòÉ 356. ReviewRevisions ΓòÉΓòÉΓòÉ

This function initiates Revision Marking Review. If any revisions are found,
the Review Revision Marking dialog box is displayed and the user may decide
whether to accept, cancel, or skip the revision. This function does not
automatically accept or cancel a revision. This function is equivalent to
choosing Tools Revision Marking and choosing Review Revisions.


Syntax
ReviewRevisions()

Return Value
1  (TRUE) if the mode was changed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the mode could not be changed.

Example
FUNCTION Example()
' Review revisions and turn off revision marking
RevisionMarking(2 0)
ReviewRevisions()
END FUNCTION

See also:

    RevisionMarking
    RevisionMarkOpts





ΓòÉΓòÉΓòÉ 357. RevisionInsertion ΓòÉΓòÉΓòÉ

This function marks selected text as a revision insertion. This function is
equivalent to choosing Edit Mark Text Revision Insertion.


Syntax
RevisionInsertion()

Return Value
1 (TRUE) if the revision was accepted.
0 (NoAction) if no action was taken.

Example
FUNCTION Example()
Message("Marking selected text for revision insertion.")
RevisionInsertion()
END FUNCTION

See also:

    ReviewRevisions
    RevisionMarking
    RevisionMarkOpts



ΓòÉΓòÉΓòÉ 358. RevisionMarking ΓòÉΓòÉΓòÉ

This function turns revision marking on or off and lets you determine what
revision marking function to perform. This function is equivalent to choosing
Tools Revision Marking.


Syntax
RevisionMarking(Which, State)
Which defines which function to perform and can be one of the following:
    MarkRevisions (1) - Changes the revision state only
    ReviewRevisions (2) - Step through each revision mark from the beginning of
    the document
    AcceptRevisions (3) - Accept all revisions in the document
    CancelRevisions (4) - Cancel all revisions in the document
State is a flag which determines if revision marking is in effect and can be
one of the following:
    RevOn (1) - Turn on revision marking
    RevOff (0) - Turn off revision marking

To display the Revision Marking dialog box and allow the user to select the
revision marking function: RevisionMarking

Return Value
1  (TRUE) if the changes were accepted.
0  (UserCancel/FALSE) if the user canceled the function or if no action was
taken.

Example
FUNCTION Example()
Message("Turn on revision marking.")
RevisionMarking(1, 1)
END FUNCTION

See also:

    ReviewRevisions
    RevisionInsertion
    RevisionMarkOpts


ΓòÉΓòÉΓòÉ 359. RevisionMarkOpts ΓòÉΓòÉΓòÉ

This function is used to set the attributes and colors for marking insertions
and deletions for revision marking. Options may also be changed for showing
marks in margins. This function is equivalent to choosing Tools Revision
Marking and choosing Options.


Syntax
RevisionMarkOpts(InsFlag, InsUseColor, InsColor, DelFlag, DelChar, DelUseColor,
DelColor, MarksFlag, MarksChar, Position)
InsFlag defines which attributes to use for marking insertions and can be one
of the following:
    RevNoAttr (0) - No attribute set for marking insertions
    RevBold (1) - Use bold attribute for marking insertions
    RevItalic (2) - Use italic attribute for marking insertions
    RevbUnderline (3) - Use underline attribute for marking insertions
    RevDblUnderline (4) - Use double underline attribute for marking insertions
InsUseColor indicates if color is to be used for marking insertions and can be
one of the following:
    ColorOn (1) - Use color
    ColorOff (0) - Do not use color
InsColor is the color to use for marking insertions and can be one of the
following:
    White (16777215)
    Cyan (16776960)
    Yellow (65535)
    Magenta (16711935)
    Green (65280)
    Red (255)
    Blue (16711680)
    Black (0)
DelFlag indicates which attributes to use for marking deletions and can be one
of the following:
    RevNoAttr (0) - No attribute set for marking deletions
    RevStrikeThru (1) - Strike through the delete characters
    RevOverstrike (2) - Use the DelChar parameter to overstrike the deleted
    characters
DelChar is the overstrike character to use for marking deletions.
DelUseColor sets the flag if color is to be used for marking deletions and can
be one of the following:
    ColorOn (1) - Use color
    ColorOff (0) - Do not use color
DelColor is the color to use for marking deletions and can be one of the
following:
    White (16777215)
    Cyan (16776960)
    Yellow (65535)
    Magenta (16711935)
    Green (65280)
    Red (255)
    Blue (16711680)
    Black (0)
MarksFlag defines the kind of mark used to show marks in margins. It is one of
the following values:
    RevNoAttr (0) - No attribute set for showing marks in margins
    RevBars (1) - Use revision bar when showing marks in margins
    RevChar (2) - Use the MarksChar to show marks in margins
MarksChar is the character used for showing marks in margins.
Position defines in which margin the marks indicator is displayed and can be
one of the following:
    RevMarkLeft (0) - Show marks in left margin
    RevMarkRight (1) - Show marks in right margin
    RevMarkRightLeft (2) - Show marks for even pages in the left margin and odd
    pages in the right margin

To display the  revision  marking  options dialog box and allow the user to
select the options: RevisionMarkOpts

Return Value
1 if the attributes are set.
0 (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
RevisionMarkOpts(RevItalic, ColorOn, 16711680, RevStrikeThru, 0, ColorOn, 255,
RevBars, 0, RevMarkRightLeft)
RevisionMarking(1, 1)
END FUNCTION

See also:

    ReviewRevisions
    RevisionInsertion
    RevisionMarking


ΓòÉΓòÉΓòÉ 360. RexxCmd ΓòÉΓòÉΓòÉ

This function executes an external REXX command file and can pass arguments to
REXX. REXX can retrieve the arguments by using the ARG function.


If the REXX script includes a RETURN FINALRESULT statement, the return value is
available to the Ami Pro macro as the return value.

Syntax
RexxCmd(REXX_CMD_FILE, [Arg1, Arg2, ...])
REXX_CMD_FILE is the name of the REXX command file to execute.
Arg1, Arg2... are any input values expected by the REXX command file.

Return Value
Return value from REXX script.

Example
Function Main()
Fname = "Charlie"
Stat = RexxCmd("c:\amipro\macros\myrexx.cmd", Fname)
End Function

See also:

    Integrating REXX Commands
    RexxFunction





ΓòÉΓòÉΓòÉ 361. RexxFunction ΓòÉΓòÉΓòÉ

This functions executes a single REXX statement from within an Ami Pro macro.
This function takes a string giving the REXX statement, and returns the REXX
return value from that statement.


You must use the REXX statement RETURN to obtain a return variable.

Syntax
RexxFunction(REXX_statement)
REXX_statement is the REXX statement you want to execute. You must use the
correct REXX syntax for that statement.
For additional information on REXX statements, select the information icon in
the OS/2 System folder and select REXX information.

Return Value
OK = 0 or the return variable from REXX.

Example
Function Main()
Number = -100
' get the absolute value and a random number
AbsNum = RexxFunction("return abs({number})")
RndNum = RexxFunction("return Random(100)")
Message("Absolute value is {AbsNum}, random number is {RndNum}")

' this will load the RexxUtil dll
RexxFunction("Call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'")
RexxFunction ("Call SysloadFuncs")

DriveC = RexxFunction("return SysDriveInfo(""c:"")")
Message("Infomation about drive c: {DriveC}")

End function

See also:

    Integrating REXX Commands
    RexxCmd



ΓòÉΓòÉΓòÉ 362. Right ΓòÉΓòÉΓòÉ

This function retrieves the specified number of characters from the right end
of the specified string.


Syntax
Right$(Text, Length)
Text is the string to parse.
Length is the number of characters from the right end of the string to parse.

Return Value
A string containing the specified characters parsed from the original string
that may be the null string.

Example
FUNCTION Example()
DEFSTR Char;
OpenFile = GetOpenFileName$()
I = LEN(OpenFile)
WHILE "\" != Assign(&Char, MID$(OpenFile, I, 1))
    I = I - 1
WEND
FileName = Right$(OpenFile, (LEN(OpenFile) - I))
Message("The current file is {FileName}.")
END FUNCTION

See also:

    Instr
    Left$
    LEN
    MID$


ΓòÉΓòÉΓòÉ 363. RightAlign ΓòÉΓòÉΓòÉ

This function acts as a toggle to turn right alignment on or off for a
paragraph of text. This function is equivalent to choosing Text Alignment
Right.


Syntax
RightAlign()

Return Value
1  (TRUE) if the text was right aligned, or if alignment was removed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
String = "This is a line of Text. "
FOR i = 1 to 10
    Paste()
NEXT
LeftAlign()
END FUNCTION

See also:

    Center
    Justify
    LeftAlign
    NormalText


ΓòÉΓòÉΓòÉ 364. RightEdge ΓòÉΓòÉΓòÉ

This function scrolls the document to the right edge of the page without moving
the insertion point. This function is equivalent to dragging the slider box on
the horizontal scroll bar to the extreme right.


Syntax
RightEdge()

Return Value
This function returns 1.

Example
FUNCTION Example()
RightEdge()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 365. Round ΓòÉΓòÉΓòÉ

This function rounds a number to an integer. Values with fractional parts
greater than or equal to .5 are rounded up to the next highest integer value.
Those with fractional parts less than .5 are rounded down to the next lowest
integer.


Syntax
Round(Value)
Value is the number to be rounded.

Return Value
This function returns an integer.

Example
FUNCTION Example()
Number = Query$("What number do you want to round?")
Round(Number)
END FUNCTION

See also:

    IsNumeric
    Mod


ΓòÉΓòÉΓòÉ 366. RunLater ΓòÉΓòÉΓòÉ

This function allows one macro to start another at a later time. While waiting
for the called macro to start, control is turned back to the user.


Syntax
RunLater(MacroName[!Function[(parm1[, parm2...])]][, Hours:]Minutes[.Seconds])
MacroName is the macro to run at a later time.
Hours is the number of hours to wait before playing back the macro.
Minutes is the number of minutes to wait before playing back the macro.
Seconds is the number of seconds to wait before playing back the macro.

Return Value
This function does not return a value.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
RunLater("{MacFile}!Example2()", 0.10)
END FUNCTION

FUNCTION Example2()
Message("It is now 10 seconds after you pushed ""OK"" in the message box.")
END FUNCTION

See also:

    GetTime
    Pause


ΓòÉΓòÉΓòÉ 367. Save ΓòÉΓòÉΓòÉ

This function saves the currently active document to disk. This function is
equivalent to choosing File Save. This function cannot be used to save an
Untitled document. You should use the SaveAs function to save an Untitled
document.


Syntax
Save()

Return Value
1  (TRUE) if the file was saved.
0  (UserCancel/FALSE) if the user canceled the function.
-2  (GeneralFailure) if the file was not saved, if the file was password
protected and password verification failed, if the file was read-only, or if
the file to be saved was untitled.

Example
FUNCTION Example()
result = Save()
IF result = 0
    Message("Use SaveAs")
ENDIF
END FUNCTION

See also:

    Revert
    SaveAs


ΓòÉΓòÉΓòÉ 368. SaveAs ΓòÉΓòÉΓòÉ

This function saves the document on the screen with a different name or file
type. This function is equivalent to choosing File Save As.


Syntax
SaveAs(FileName, Options, Description, App)
FileName is the name of the file to save the document as. This parameter may
optionally include a path.
Options are options for saving the file if saving as an Ami Pro document. It is
one of the following values:
    0 - Ami Pro file or Non-ASCII file
    4 - ASCII file
    KeepFormat (32) - Keep format
    Password (64) - Use password protection
If saving as an Ami Pro Macro file type, use only the KeepFormat value.
Description is the document description of the new file.
App is the name of the filter that appears in the amipro3.ini file. Use the
null string ("") to specify an Ami Pro file.

To display the Save As dialog box and allow the user to choose the name of the
file: SaveAs

Return Value
1  (TRUE) if the file was saved.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the file was not saved.

Example
FUNCTION Example()
SaveAs("test.sam", 32, "Test file", "")
END FUNCTION

See also:

    FileOpen
    Revert
    Save




ΓòÉΓòÉΓòÉ 369. SaveAsNewStyle ΓòÉΓòÉΓòÉ

This function saves the current document's paragraph styles to a new paragraph
style sheet. This function is equivalent to choosing Style Save as a Style
Sheet.


Syntax
SaveAsNewStyle(Name, WithContents, MacroName, RunMacro, Description)
Name is the name to name the new style sheet.
WithContents is a flag that determines whether to save the document's contents
in the new paragraph style sheet and can be one of the following:
    (1) - Save the contents of the file in the paragraph style sheet
    (0) - Do not save the file's contents in the paragraph style sheet
MacroName is the name of the macro to run when a new file is opened with the
selected paragraph style sheet.
RunMacro determines whether or not to run MacroName when the new file with the
selected paragraph style sheet is opened. It is one of the following values:
    (1) - Run the macro
    (0) - Do not run the macro
Description is the style sheet description.

To display a dialog box to allow the user to select the name for the new
paragraph style sheet: SaveAsNewStyle

Return Value
1  (TRUE) if the paragraph style sheet was saved.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
SaveAsNewStyle("Example.sty", 1, "", "", "My example style sheet")
END FUNCTION

See also:



ΓòÉΓòÉΓòÉ 370. ScreenDown ΓòÉΓòÉΓòÉ

This function scrolls the document down one screen without moving the insertion
point. This function is equivalent to clicking above the slider box on the
vertical scroll bar.


Syntax
ScreenDown()

Return Value
1  (TRUE) if the document was able to scroll.
-2  (GeneralFailure) if the document could not be scrolled.

Example
FUNCTION Example()
ScreenDown()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenLeft
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 371. ScreenLeft ΓòÉΓòÉΓòÉ

This function scrolls the document left one screen without moving the insertion
point. This function is equivalent to clicking to the right of the slider box
on the horizontal scroll bar.


Syntax
ScreenLeft()

Return Value
1  (TRUE) if the document was able to scroll.
-2  (GeneralFailure) if the document could not be scrolled.

Example
FUNCTION Example()
ScreenLeft()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenRight
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 372. ScreenRight ΓòÉΓòÉΓòÉ

This function scrolls the document right one screen without moving the
insertion point. This function is equivalent to clicking to the left of the
slider box on the horizontal scroll bar.


Syntax
ScreenRight()

Return Value
1  (TRUE) if the document was able to scroll.
-2  (GeneralFailure) if the document could not be scrolled.

Example
FUNCTION Example()
ScreenRight()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenUp
    TopOfFile


ΓòÉΓòÉΓòÉ 373. ScreenUp ΓòÉΓòÉΓòÉ

This function scrolls the document up one screen without moving the insertion
point. This function is equivalent to clicking below the slider box on the
vertical scroll bar.


Syntax
ScreenUp()

Return Value
1  (TRUE) if the document was able to scroll.
-2  (GeneralFailure) if the document could not be scrolled.

Example
FUNCTION Example()
ScreenUp()
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    TopOfFile




ΓòÉΓòÉΓòÉ 374. SelectColumn ΓòÉΓòÉΓòÉ

This function selects a column in a table. The column that contains the
insertion point is selected. This function is equivalent to choosing Table
Select Column.


The insertion point must be in the table before performing this function.

Syntax
SelectColumn()

Return Value
1 (TRUE) if the column is selected.
0 (NoAction) if no action is taken. The table may not exist or may not be
selected.

Example
FUNCTION Example()
SelectColumn()
END FUNCTION

See also:

    SelectEntireTable
    SelectRow


ΓòÉΓòÉΓòÉ 375. SelectEntireTable ΓòÉΓòÉΓòÉ

This function selects the entire table. This function is equivalent to choosing
Table Select Entire Table.


The insertion point must be in the table before performing this function.

Syntax
SelectEntireTable()

Return Value
1 (TRUE) if the entire table is selected.
0 (NoAction) if no action is taken. The table may not exist or may not be
selected.

Example
FUNCTION Example()
SelectEntireTable()
END FUNCTION

See also:

    DeleteEntireTable
    SelectColumn
    SelectRow


ΓòÉΓòÉΓòÉ 376. SelectFrameByName ΓòÉΓòÉΓòÉ

This function allows you to select a frame by name. Use the MarkBookMark
function to name the frames.


Syntax
SelectFrameByName(FrameName)
FrameName is the name of the frame you want to select.

Return Value
0  if the frame could not be found.

Example
FUNCTION Example()
myframe = Query$("Enter the name of the bookmark set to the frame you want to
select:")
SelectFrameByName(myframe)
END FUNCTION

See also:

    GoToCmd
    MarkBookMark


ΓòÉΓòÉΓòÉ 377. SelectRow ΓòÉΓòÉΓòÉ

This function selects a row in a table. The row that contains the insertion
point is selected. This function is equivalent to choosing Table Select Row.


The insertion point must be in the table before performing this function.

Syntax
SelectRow()

Return Value
1 (TRUE) if the row is selected.
0 (NoAction) if no action is taken. The table may not exist or may not be
selected.

Example
FUNCTION Example()
SelectRow()
END FUNCTION

See also:

    SelectColumn
    SelectEntireTable


ΓòÉΓòÉΓòÉ 378. SelectStyle ΓòÉΓòÉΓòÉ

This function allows the user to select a new paragraph style. This function is
equivalent to choosing Style Select a Style. This function does not
automatically select a new paragraph style.


To have the macro select a paragraph style for the user, use the SetStyle
function.

Syntax
SelectStyle()

Return Value
1  (TRUE) if the new paragraph style was selected.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the paragraph style was not selected.

Example
FUNCTION Example()
SelectStyle()
END FUNCTION

See also:

    ModifyStyle
    SetStyle


ΓòÉΓòÉΓòÉ 379. SelectWindow ΓòÉΓòÉΓòÉ

This function allows you to give any document in Ami Pro the focus and make it
the active document. This function is equivalent to choosing Window and
selecting an open file name.


Syntax
SelectWindow(FileName)
FileName is the name of the document to get the focus. This name must match the
name in the title bar of the document.

Return Value
0  if the document was not selected, or was not found.

Example
FUNCTION Example()
filename = Query$("Name the window to select (name must match exactly).")
SelectWindow(filename)
END FUNCTION

See also:

    CascadeWindow
    NewWindow
    NextWindow
    TileWindow


ΓòÉΓòÉΓòÉ 380. SendFrameToBack ΓòÉΓòÉΓòÉ

This function sends the selected frame to the rear of a stack of frames. This
function is equivalent to choosing Frame Send to Back.


Syntax
SendFrameToBack()

Return Value
1  (TRUE) if the frame was sent to the back.
0  (NoAction) if no action was taken because the frame was already in the back.

Example
FUNCTION Example()
x = strfield$(CursorPosition$(), 1, ",")
y = strfield$(CursorPosition$(), 2, ",")
AddFrame(x, y, (x + 1440), (y - 1440))
MarkBookMark("Frame1", AddBookmark)
AddFrame((x + 360), (y - 360), (x + 1800), (y - 1800))
MarkBookMark("Frame2", AddBookmark)
SendFrameToBack()
MarkBookMark("Frame1", FindBookmark)
Message("The First frame is in front.")
MarkBookMark("Frame2", FindBookmark)
BringFrameToFront()
Message("The Second frame is in front.")
END FUNCTION

See also:

    AddFrame
    AddFrameDLG
    BringFrameToFront
    GoToCmd



ΓòÉΓòÉΓòÉ 381. SendMail ΓòÉΓòÉΓòÉ

This functions allows you to send a mail message using a mail server.
Currently, Ami Pro supports cc:Mail and Lotus Notes. If the text has been
selected in the current document, the text is copied to the clipboard and then
sent as a note. This function is equivalent to choosing File Send Mail.


You can only use one mail server. This function is only available if a mail
server compatible with Ami Pro is installed.

Syntax
SendMail(Attach)
Attach is used to save and attach the active document to the note. It is one of
the following values:
    Attach (1) - Save and attach the active document to the note
    No (0) - Do not attach the active document to the note

To display the Send Mail dialog box: SendMail

Return Value
1  (TRUE) if the mail was sent.
0  (UserCancel/FALSE) if the user canceled the function or if no action was
taken.
-2  (GeneralFailure) if the mail server was not found or if it could not be
activated.

Example
FUNCTION Example()
Message("Saving and sending this doc")
Save()
SendMail(1)
END FUNCTION

See also:

    ReadMail


ΓòÉΓòÉΓòÉ 382. SetBackPath ΓòÉΓòÉΓòÉ

This function sets the default path for backup files. This function is
equivalent to choosing Tools User Setup and choosing Paths.


Syntax
SetBackPath(NewPath)
NewPath is the desired new backup path.

Return Value
1  (TRUE) if the path was successfully set.
-2  (BadPath) if the path could not be set because of an invalid directory
name.

Example
FUNCTION Example()
Backup = Query$("Please enter the desired backup path:" GetBackPath$())
Docs = Query$("Please enter the desired document path:" GetDocPath$())
Styles = Query$("Please enter the desired styles path:" GetStylePath$())
SetDocPath(Docs)
SetStylePath(Styles)
SetBackPath(Backup)
END FUNCTION

See also:

    GetBackPath$
    GetDocPath$
    GetStylePath$
    SetDocPath
    SetStylePath


ΓòÉΓòÉΓòÉ 383. SetDataFile ΓòÉΓòÉΓòÉ

This function sets the data and description file for the InsertMerge function.


Syntax
SetDataFile(RecFile, RecFileFlag, DescFile, DescFileFlag)
RecFile is the record file to use when performing a merge.
RecFileFlag is the flag to identify whether the DataFile is an Ami Pro file. If
it is an Ami Pro file, the RecFileFlag parameter should be set to 0.
DescFile is the description file to use when the record file is not an Ami Pro
file. If no description file is needed, insert an empty string ("").
DescFileFlag is the flag to identify whether the DescFile is an Ami Pro file.
If it is an Ami Pro file, the DescFileFlag parameter should be set to 0.

Return Value
1  (TRUE) if the record and description files are set.
-3  if invalid input.
0  (NoAction) if no action was taken.

Example
FUNCTION Example()
SetDataFile ("Testrel.sam", 0, "", 0)
InsertMerge()
END FUNCTION

See also:

    InsertMerge


ΓòÉΓòÉΓòÉ 384. SetDefOptions ΓòÉΓòÉΓòÉ

This function sets editing defaults for using Ami Pro. This function is
equivalent to choosing Tools User Setup and choosing Options.


Syntax
SetDefOptions(Options, HotZone)
Options is a flag containing default options and can be one or more of the
following:
    DoWindows (2) - Control widows and orphans in the document
    (4) Print in background (speed option)
    (16) - Save for fast display graphic display speed option - saves screen
    snapshot files (~ISD*.TMP) as part of the document.
    (64) - Conserve disk space graphic display speed option - stores screen
    snapshot files (~ISD*.TMP) in RAM when a page is displayed.
    (128) - Hyphenate last word in paragraph
    (256) - Hyphenate last word in column/page
To set more than one option, add the options together.
HotZone is the number of characters to use for the hyphenation hot zone. You
can specify any number between 2 and 9.

To display the Defaults dialog box and allow the user to select editing
defaults: UserSetup

Return Value
1  (TRUE) if the default settings were successfully set.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
SetDefOptions(0, 5)
END FUNCTION

See also:

    LoadOptions
    SetBackPath
    SetDocPath
    SetStylePath
    UserSetup
    ViewPreferences


ΓòÉΓòÉΓòÉ 385. SetDlgCallBack ΓòÉΓòÉΓòÉ

This function is used to flag a control in the next displayed dialog box as a
callback. If the contents of the control are modified once the dialog box is
displayed, the specified macro is called.


A callback is a macro function that is initiated by a displayed dialog box and
executes without closing that box.

Syntax
SetDlgCallBack(ID, MacroName!Function)
ID is the ID of the control that you want to monitor.
Macroname is the filename of the macro file containing the function to be
executed. If the macro file does not exist in the current macros directory, the
full path must be used.
Function is the name of the function to be executed if the specified object is
modified. MacroName and Function are separated by an exclamation mark.
You may not send any parameters or even use parenthesis with this parameter.
The specified function is called with three parameters: the windows handle for
the dialog box, the ID specified, and the contents of the specified object.

Return Value
This function does not return a value.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
SetDlgCallBack(50, "{MacFile}!Message1")
Box = DialogBox(".", "ExampleBox")
IF Box = 0
    EXIT FUNCTION
ENDIF
TYPE(GetDialogField$(8002))
END FUNCTION

FUNCTION Message1(hdlg, id, text)
Name = GetDlgItemText(hdlg, 8000)
Message("The contents of the first box are {Name}.")
Message("We will now fill the second box with the inverse of {Name}.")
FOR I = len(Name) to 1 step -1
    Name2 = strcat$(Name2, MID$(Name, I, 1))
NEXT
SetDlgItemText(hdlg, 8002, Name2)
END FUNCTION

DIALOG ExampleBox
-2134376448 8 106 38 160 54 "" "" "Sample Dialog Box"
FONT 6 "Helv"
50 6 62 12 8000 1350631552 "edit" "" 0
4 6 44 10 1000 1342177280 "static" "Your Name:" 0
50 20 62 12 1003 1342177287 "static" "" 0
4 22 44 10 1002 1342177280 "static" "Reversed:" 0
52 22 58 8 8002 1342177280 "static" "" 0
116 4 40 14 1 1342242817 "button" "OK" 0
116 20 40 14 2 1342242816 "button" "Cancel" 0
100 36 56 14 50 1342242816 "button" "&Run Example..." 0
END DIALOG

See also:

    DialogBox
    FillEdit
    FillList
    GetDialogField$
    GetDLGItem
    GetDLGItemText
    SetDLGItemText


ΓòÉΓòÉΓòÉ 386. SetDlgItemText ΓòÉΓòÉΓòÉ

This function sets the contents of a specified control in a callback, while the
dialog box remains displayed.


Syntax
SetDlgItemText( Handle, ID, Text)
Handle is the windows handle to the dialog box to be modified and it was passed
to the callback function.
ID is the control ID in which to set the contents.
Text is the string data (if modifying an edit, combo, or list box, or static
text), or a Boolean TRUE or FALSE value (if modifying a radio button or check
box) to set the contents of the control to.

Return Value
1  (TRUE) if the function was successful.
0  (FALSE) if the function failed.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
SetDlgCallBack(50, "{MacFile}!Message1")
Box = DialogBox(".", "ExampleBox")
IF Box = -1
    Message("Could not find dialog box!")
    EXIT FUNCTION
ELSEIF Box = 0
    EXIT FUNCTION
ENDIF
TYPE(GetDialogField$(8002))
END FUNCTION

FUNCTION Message1(hdlg, id, text)
Name = GetDlgItemText(hdlg, 8000)
Message("The contents of the first box are {Name}.")
Message("We will now fill the second box with the inverse of {Name}.")
FOR I = len(Name) to 1 step -1
    Name2 = strcat$(Name2, MID$(Name, I, 1))
NEXT
SetDlgItemText(hdlg, 8002, Name2)
END FUNCTION

DIALOG ExampleBox
-2134376448 8 106 38 160 54 "" "" "Sample Dialog Box"
FONT 6 "Helv"
50 6 62 12 8000 1350631552 "edit" "" 0
4 6 44 10 1000 1342177280 "static" "Your Name:" 0
50 20 62 12 1003 1342177287 "static" "" 0
4 22 44 10 1002 1342177280 "static" "Reversed:" 0
52 22 58 8 8002 1342177280 "static" "" 0
116 4 40 14 1 1342242817 "button" "OK" 0
116 20 40 14 2 1342242816 "button" "Cancel" 0
100 36 56 14 50 1342242816 "button" "&Run Example..." 0
END DIALOG

See also:

    DialogBox
    FillEdit
    FillList
    GetDialogField$
    GetDLGItem
    GetDLGItemText


ΓòÉΓòÉΓòÉ 387. SetDocPath ΓòÉΓòÉΓòÉ

This function sets the default path for document storage. This function is
equivalent to choosing Tools User Setup and choosing Paths.


Syntax
SetDocPath(NewPath)
NewPath is the desired new default document path.

Return Value
1  (TRUE) if the path was successfully set.
-2  (GeneralFailure) if the path could not be set.

Example
FUNCTION Example()
Backup = Query$("Please enter the desired backup path:" GetBackPath$())
Docs = Query$("Please enter the desired document path:" GetDocPath$())
Styles = Query$("Please enter the desired styles path:" GetStylePath$())
SetDocPath(Docs)
SetStylePath(Styles)
SetBackPath(Backup)
END FUNCTION

See also:

    GetBackPath$
    GetDocPath$
    GetStylePath$
    SetBackPath
    SetStylePath
    UserSetup
    ViewPreferences


ΓòÉΓòÉΓòÉ 388. SetDocVar ΓòÉΓòÉΓòÉ

This function creates or updates a document variable in the current document. A
document variable is used to store information in the document and may be
retrieved by using the GetDocVar function.


Syntax
SetDocVar(Name, Text)
Name is the name for the document variable by which it may be accessed.
Text is the information that is stored in the document variable.
The two strings combined must not exceed 250 bytes in length.

Return Value
This function returns 1.

Example
FUNCTION Example()
SetDocVar("answer 1", "George Washington")
END FUNCTION

See also:

    GetDocVar


ΓòÉΓòÉΓòÉ 389. SetFormula ΓòÉΓòÉΓòÉ

This function inserts a formula into the current table cell. This function is
equivalent to choosing Table Edit Formula.


Syntax
SetFormula(Formula)
Formula is the formula that is typed into the table cell.
To allow the user to type the formula for the cell: EditFormula

Return Value
1  (TRUE) if the formula was inserted.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
radius = Query$("What is the radius?")
SetFormula(3.1415926 * radius * radius)
END FUNCTION

See also:

    EditFormula


ΓòÉΓòÉΓòÉ 390. SetFrameDefaults ΓòÉΓòÉΓòÉ

This function sets the defaults for the frame. This function is equivalent to
choosing Frame Modify Frame Layout and choosing Make Default.


You must call FrameModInit before calling SetFrameDefaults. The FrameModFinish
function must be called after this function to accept the modifications.

Syntax
SetFrameDefaults(BorderWhere, ThickType, PosType, 0, ShadeType, BackType,
DefType, LeftMargin, BottomMargin, TopMargin, RightMargin, ShadowLeft,
ShadowTop, ShadowRight, ShadowBottom, ShadowColor, Rounded)
BorderWhere is the lines around a frame. It is one of the following values:
    1 - All
    2 - Left
    4 - Right
    8 - Top
    16 - Bottom
ThickType is the thickness of the border. It is one of the following values:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rule
    DoubleTwoPoint (9) - Parallel two point rule
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
PosType is the position of the border around a frame. It is one of the
following values:
    1 - Middle
    2 - Inside
    3 - Outside
    4 - Close to Inside
    5 - Close to outside
You can only choose one value for the PosType parameter.
ShadeType sets the line color. It can be one of the following values:
    Black - 0
    Blue - 16727905
    Cyan - 16776960
    Green - 65280
    Magenta - 16711935
    MedBlue - 16744448
    Orange - 33279
    Pink - 8388863
    Purple - 16711809
    Red - 255
    White - 16777215
    Yellow - 65535
BackType sets the background color. It can be one of the values listed under
ShadeType.
DefType is a setting based on: how the text should wrap around a frame, whether
a frame is transparent or opaque, where it is placed on a page, and whether a
macro is assigned to a frame. It is one of the following values:
    TextFrame (512) - Always use in combination with other values. It is a
    required value.
    Opaque (64) - Hide text or picture behind frame
    Transparent(0) - Displays text or pictures behind frame.
    Wraparound (128) - Display text above, below, to the left, or to the right
    of the frame
    NoWrapBeside (131072) - Display text above and below frame, but not to the
    left or right of the frame
    If you do not specify Wraparound or NoWrapBeside, the frame uses the
    default setting of no wrap around.
    AnchorFrame (524288) - Used to anchor frame in its current position or to a
    carriage return. You cannot use any repeat values with this value.
    RepeatFrame (256) - Repeat frame on multiple pages. To repeat on all pages,
    do not use in combination with RepeatEven or RepeatOdd.
    RepeatOdd (8192) - Repeat frame on odd pages. Use with the RepeatFrame
    value.
    RepeatEven (4194304) - Repeat frame on even pages. Use with the RepeatFrame
    value.
    Borders (65536) - Use if frame has borders
    RunMacro (134217728) - Run a macro each time the frame is selected
You can add the values together to get the DefType parameter. The syntax is "N
&0x300c0", where "N" is the DefType value.
LeftMargin is the desired left margin of the frame in twips (1 inch = 1440
twips).
BottomMargin is the desired bottom margin of the frame in twips (1 inch = 1440
twips).
TopMargin is the desired top margin of the frame in twips (1 inch = 1440
twips).
RightMargin is the desired right margin of the frame in twips (1 inch = 1440
twips).
ShadowLeft is the distance that the shadow is offset from the left side of the
frame in twips (1 inch = 1440 twips). It can be one of the following values or
a custom value:
    None (0) - No shadow
    Shallow (57) - Shallow shadow
    Normal (100) - Normal shadow
    Deep (172) - Deep shadow
ShadowTop is the distance that the shadow is offset from the top of the frame
in twips (1 inch = 1440 twips). It can be one of the values listed under
ShadowLeft or a custom value.
ShadowRight is the distance that the shadow is offset from the right side of
the frame in twips (1 inch = 1440 twips). It can be one of the values listed
under ShadowLeft or a custom value.
ShadowBottom is the distance that the shadow is offset from the bottom of the
frame in twips (1 inch = 1440 twips). It can be one of the values listed under
ShadowLeft or a custom value.
ShadowColor sets the color for the frame shadow. It can be one of the values
listed under ShadeType.
Rounded is the percentage that the corners are rounded (0% = square and 100% =
circle).

Return Value
This function returns 1.

Example
FUNCTION Example()
SetFrameDefaults(1, 1, 1, 0, 0, 255, 1677721, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
END FUNCTION

See also:

    FrameModBorders
    FrameModFinish
    FrameModInit
    FrameModLines
    FrameModType




ΓòÉΓòÉΓòÉ 391. SetGlobalArray ΓòÉΓòÉΓòÉ

This function assigns a value stored in a local array variable element to a
global array variable element.


Syntax
SetGlobalArray(Name, Index, Value)
Name is the name or the ID number of the global array to set.
Index is the element of the array in which to place the value.
Value is the value that should be stored in the array element.

Return Value
1  (TRUE) if the value was successfully set.
0  (FALSE) if the value could not be set. If you attempt to set a global
variable that does not exist, a run-time error results.

Example
FUNCTION Example()
AllocGlobalVar("Names", 5)'Allocate space for a 5 element global variable
AllocGlobalVar("Numbers", 5)'Allocate space for a 5 element global variable
AllocGlobalVar("YourName", 1)'Allocate space for a single element global
variable.
FOR I = 1 to 5'Do the following 5 times.
    SetGlobalArray("Names", I, Query$("Enter Name Number {I}"))
    'Fill a global array with the return from QUERY
    SetGlobalArray("Numbers", I, (100/I))'Fill a global array with a number
NEXT
NewName = Query$("What is your name?")'Query the user for his/her name
SetGlobalVar("YourName", NewName)'Set a global variable to that value
CALL Example2()'Call the following function
END FUNCTION

FUNCTION Example2()
Name = GetGlobalVar$("YourName")'Get the value of the global variable
Message("Your name is {Name}.")'Message that value in a box.
FOR I = 1 to 5'Do the following 5 times.
    TheirName = GetGlobalArray$("Names", I)'Get the value of the current
 element from the array
    TheirNumber = GetGlobalArray$("Numbers", I)'Get the value of the current
 element from the array
    TYPE("Name #{I} is {TheirName}, and the number is {TheirNumber}.[Enter]")
    'Type the values to the screen.
NEXT
FreeGlobalVar("Names")'Clear the space for the first global array
FreeGlobalVar("Numbers")'Clear the space for the second global array
FreeGlobalVar("YourName")'Clear the space for the global variable
END FUNCTION

See also:

    AllocGlobalVar
    FreeGlobalVar
    GetGlobalArray$
    GetGlobalVar$
    GetGlobalVarCount
    GetGlobalVarNames
    Global Variables
    SetGlobalVar
    Using Variables


ΓòÉΓòÉΓòÉ 392. SetGlobalVar ΓòÉΓòÉΓòÉ

This function assigns the value stored in a single element local variable to a
global variable.


Syntax
SetGlobalVar(Name, Value)
Name is the name or the ID number of the global variable to set.
Value is the value to store into the global variable.

Return Value
1  (TRUE) if the value was successfully set.
0  (FALSE) if the value could not be set. If you attempt to set a global
variable that does not exist, a run-time error results.

Example
FUNCTION Example()
Again:
Count = GetGlobalVarCount()
IF Count < 1
    Count = 1
ELSE
    DIM Globals(Count)
    GetGlobalVarNames(&Globals)
    FillEdit(9000, &Globals)
ENDIF
Box = DialogBox(".", "ExampleBox")
IF Box = 0
    EXIT FUNCTION
ELSEIF Box = 3 AND GetDialogField$(9000) != ""
    FreeGlobalVar(GetDialogField$(9000))
ELSEIF Box = 4 AND GetDialogField$(9000) != ""
    Message(GetGlobalVar$(GetDialogField$(9000)))
ELSEIF Box = 5
    AllocGlobalVar(Query$("Name for new global variable:"), Query$("Number of
 elements?"))
ELSEIF Box = 6 AND GetDialogField$(9000) != ""
    SetGlobalVar(GetDialogField$(9000), Query$("What do you want in it?"))
ENDIF
GoTo Again
END FUNCTION

DIALOG ExampleBox
-2134376448 7 98 20 160 102 "" "" "Global Variables"
FONT 6 "Helv"
116 4 40 14 2 1342242817 "button" "Done" 0
116 20 40 14 3 1342242816 "button" "Free" 0
116 36 40 14 4 1342242816 "button" "Show..." 0
116 52 40 14 5 1342242816 "button" "Allocate..." 0
116 68 40 14 6 1342242816 "button" "Set..." 0
6 14 102 82 9000 1352728579 "listbox" "" 0
8 4 98 8 1000 1342177280 "static" "Currently Allocated Globals:" 0
END DIALOG

See also:

    AllocGlobalVar
    FreeGlobalVar
    GetGlobalArray$
    GetGlobalVar$
    GetGlobalVarCount
    GetGlobalVarNames
    Global Variables
    SetGlobalArray
    Using Variables




ΓòÉΓòÉΓòÉ 393. SetIconPath ΓòÉΓòÉΓòÉ

This function sets the default path for the SmartIcons files. This function is
equivalent to choosing Tools User Setup and choosing Paths.


Syntax
SetIconPath(NewPath)
NewPath is the desired new path for the SmartIcons files.

Return Value
1 (TRUE) if the path was successfully set.
-2 (GeneralFailure) if the path could not be set.

Example
FUNCTION Example()
SetIconPath("c:\amipro\icons")
END FUNCTION

See also:

    SetBackPath
    SetDocPath
    SetMacroPath
    SetStylePath
    UserSetup





ΓòÉΓòÉΓòÉ 394. SetIconSize ΓòÉΓòÉΓòÉ

This function sets the icon size of the icon set. This function is equivalent
to choosing Tools SmartIcons and choosing Icon Size.


A macro must be edited to insert this non-recordable function.

Syntax
SetIconSize(Size)
Size is one of the following values:
    (1) - Small (VGA)
    (3) - Large (Super VGA)

Return Value
1 (TRUE) if the SmartIcon size changes.
0 (NoAction) if no action is taken.

Example
FUNCTION Example()
SetIconSize(2)
END FUNCTION

See also:

    ChangeIcons
    HideIconBar
    IconBottom
    IconCustomize
    IconFloating
    IconRight
    IconTop
    ShowIconBar


ΓòÉΓòÉΓòÉ 395. SetIndexFile ΓòÉΓòÉΓòÉ

This function sets the file name used to generate an index. It records the
index file name for use in the Tools Generate Index dialog box and in the File
Master Document Index Options dialog box. This function is equivalent to
choosing File Master Document and choosing Index Options.


This function should be used prior to the Generate function when generating an
index.

Syntax
SetIndexFile(Separators, IndexFile)
Separators indicates whether or not alphabetic separators are used in the
index. It is one of the following values:
    Yes (1) - Include alphabetic separators.
    No (2) - Do not include alphabetic separators.
IndexFile is the file name for the index file.
To allow the user to view the TOC, Index dialog box and enter the index file
name: Generate

Return Value
This function returns 1.

Example
FUNCTION Example()
docpath=GetDocPath$()
' do not include alpha separators
SetIndexFile (2, "{docpath}test.sam")
END FUNCTION

See also:

    Generate
    SetTOCFile


ΓòÉΓòÉΓòÉ 396. SetMacroPath ΓòÉΓòÉΓòÉ

This function sets the default path for macro storage. This function is
equivalent to choosing Tools User Setup and choosing Paths.


Syntax
SetMacroPath(NewPath)
NewPath is the desired new default path for macros.

Return Value
1  (TRUE) if the macro path was set.
-2  (GeneralFailure) if the macro path could not be set.

Example
FUNCTION Example()
SetMacroPath("C:\Amipro\Macros")
END FUNCTION

See also:

    SetBackPath
    SetDocPath
    SetIconPath
    SetStylePath
    UserSetup


ΓòÉΓòÉΓòÉ 397. SetMasterFiles ΓòÉΓòÉΓòÉ

This function determines which files comprise a master document. It makes the
current file a master document. This function is equivalent to choosing File
Master Document and including the files for the master document.


Syntax
SetMasterFiles(Size, Count, File1[, File2...])
Size is the amount of buffer space allocated to hold the files. It is
determined by adding up all of the characters in each filename, plus the number
of files, plus one.
Count is the number of files in the master document.
File1 is the name of the first file in the list of master documents. If the
file does not exist in the current documents directory, the full path to the
file must be used.
File2 and any other files are treated the same as file1, above.

To display the Master Document dialog box and allow the user to specify the
files: MasterDoc

Return Value
1  (TRUE) if the master files list was set.
-2  (GeneralFailure) if the master files list could not be set.

Example
FUNCTION Example()
size = 1 + len("TEST.SAM") + 1
SetMasterFiles(size, 1, "TEST.SAM")
END FUNCTION

See also:

    GetMasterFilesCount
    GetMasterFiles


ΓòÉΓòÉΓòÉ 398. SetStyle ΓòÉΓòÉΓòÉ

This function assigns the named paragraph style to the current paragraph. This
function is equivalent to selecting a paragraph style name from the status bar.


Syntax
SetStyle(Style)
Style is the name of a paragraph style in the current style sheet or document.
To allow the user to select the name of the paragraph style to be used:
SelectStyle

Return Value
This function returns 1.

Example
FUNCTION Example()
curstyle = GetStyleName$()
newstyle = "Number List"
SetStyle(newstyle)
TYPE("This is what the {newstyle} style looks like.[Enter]")
SetStyle(curstyle)
END FUNCTION

See also:

    GetStyleName$
    ModifyStyle
    SelectStyle




ΓòÉΓòÉΓòÉ 399. SetStylePath ΓòÉΓòÉΓòÉ

This function sets the default path for style sheet storage. This function is
equivalent to choosing Tools User Setup and choosing Paths.


Syntax
SetStylePath(NewPath)
NewPath is the desired new path for paragraph style sheets.

Return Value
1  (TRUE) if the path was successfully set.
-2  (GeneralFailure) if the path could not be set.

Example
FUNCTION Example()
Backup = Query$("Please enter the desired backup path:" GetBackPath$())
Docs = Query$("Please enter the desired document path:" GetDocPath$())
Styles = Query$("Please enter the desired styles path:" GetStylePath$())
SetDocPath(Docs)
SetStylePath(Styles)
SetBackPath(Backup)
END FUNCTION

See also:

    GetBackPath$
    GetDocPath$
    GetStylePath$
    SetBackPath
    SetDocPath
    SetIconPath
    UserSetup


ΓòÉΓòÉΓòÉ 400. SetTOCFile ΓòÉΓòÉΓòÉ

This function sets the destination file for a table of contents that was
generated from the current file. It records the information for use in the
Tools Generate TOC dialog box and in the File Master Document TOC Options
dialog box. This function is equivalent to choosing File Master Document and
choosing TOC Options.


This function should be used prior to the Generate function when creating a
table of contents.

This function does not check the path to see if it is valid.

Syntax
SetTOCFile(TOCFile)
TOCFile is the filename for the generated table of contents.

To allow the user to view the TOC, Index dialog box and enter the TOC file
name: Generate.

Return Value
This function returns 1.

Example
FUNCTION Example()
SetTOCFile("TestToc.sam")
END FUNCTION

See also:

    Generate



ΓòÉΓòÉΓòÉ 401. ShowIconBar ΓòÉΓòÉΓòÉ

This function displays the set of SmartIcons in its default location on the
screen. This function is equivalent to choosing View Show SmartIcons.


Syntax
ShowIconBar()

Return Value
1  (TRUE) if the SmartIcon bar is displayed.
0  (NoAction) if no action was taken because the SmartIcon bar was already
displayed.

Example
FUNCTION Example()
ReturnValue = HideIconBar()
IF ReturnValue != 1
    IF Decide("Icon bar already hidden! Would you like it displayed?")
       ShowIconBar()
    ENDIF
ENDIF
END FUNCTION

See also:

    HideIconBar
    IconBottom
    IconCustomize
    IconFloating
    IconLeft
    IconRight
    IconTop
    ShowTabRuler
    ToggleIconBar
    ToggleIconBar
    ViewPreferences


ΓòÉΓòÉΓòÉ 402. ShowTabRuler ΓòÉΓòÉΓòÉ

This function displays the tab ruler at the top of the screen. This function is
equivalent to choosing View Show Ruler.


Syntax
ShowTabRuler()

Return Value
1  (TRUE) if the tab ruler is displayed.
0  (NoAction) if no action was taken because the tab ruler was already
displayed.

Example
FUNCTION Example()
ShowTabRuler()
END FUNCTION

See also:

    HideTabRuler
    ShowIconBar
    ToggleTabRuler
    ViewPreferences


ΓòÉΓòÉΓòÉ 403. SingleStep ΓòÉΓòÉΓòÉ

This function allows you to debug macros by stepping through each macro
statement one line at a time.


SingleStep uses two modes. In the first of these, if you have the macro to be
debugged open in a window and a SingleStep statement in it, the line currently
executing is highlighted in the macro file and a modeless dialog box displays.
If the macro to be debugged is not open, a dialog box displays the currently
running statement.

If the macro is in a window you can:
    Resume - Removes the dialog box and continues to the next break point,
    continues to the next SingleStep(1), or goes to the end of the macro.
    Single Step - Executes the current instruction then pauses again.
    Step Through - If a CALL statement is made, the macro from the CALL
    statement executes to completion and control returns to the original macro.
    Variables - This brings up a modal dialog box showing the list of local
    variables currently set in the currently running macro. You may change the
    contents of a variable here at run time. If the variable is an array, the
    number of elements in the array display and may not be changed.
    Break Points - This brings up a modal dialog box showing the list of
    currently active breakpoints. The Break Points list box lists the filename,
    an exclamation point, the function name, a period, and then the line number
    within that function.
    Set BP - This sets a break point on the current line. This assumes, of
    course, that you are still in the macro window or in another window that
    contains a running macro.
    Break points cannot be set on empty lines or commented lines or lines with
    ELSE, WEND, or ENDIF. Break points may only be placed on a line with an
    executable code statement and it must be after a SingleStep() function in
    the macro.
    Cancel - This cancels the macro. If your macro has an ONCANCEL statement,
    it is executed.

If your macro modifies open documents, make sure these documents are not the
currently executing macros. Note that when the macro first pauses, the line
about to be executed is selected and can easily be deleted.

Syntax
SingleStep(State)
State determines whether single step mode is off (0) or on (1).

Return Value
This function does not return a value.

Example
FUNCTION Example()
SingleStep(1)
FOR I = 1 to 10
    TYPE("Hello...")
NEXT
END FUNCTION

See also:

    AnswerMsgBox
    DebuggingMacros
    IgnoreKeyboard
    KeyInterrupt
    Macro Error Messages
    Messages
    UserControl
    Using the ONCANCEL Statement
    Using the SingleStep and IgnoreKeyboard Functions






ΓòÉΓòÉΓòÉ 404. SizeColumnRow ΓòÉΓòÉΓòÉ

This function sets the column and row width and height. This function is
equivalent to choosing Table Column/Row Size. If the automatic row height
option is set for the table, the row height option is ignored.


Syntax
SizeColumnRow(ColWidth, 0, RowHeight, 0)
ColWidth is the width of the column in twips.
RowHeight is the height of the row in twips.
Multiply the desired number of inches by 1440 to determine the value in twips.
(1 inch = 1440 twips).

To display a dialog box to allow the user to size columns and rows:
SizeColumnRow

Return Value
1  (TRUE) if the rows and columns were sized.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the rows and columns were not sized.

Example
FUNCTION Example()
SizeColumnRow(720, 0, 180, 0)
END FUNCTION

See also:

    DeleteColumnRow
    InsertColumnRow


ΓòÉΓòÉΓòÉ 405. SmallCaps ΓòÉΓòÉΓòÉ

This function sets the small capitalization for selected text or for all
following text if no text is selected. It acts as a toggle, turning off small
caps if it is currently on, and turning on small caps if it is currently off.
This function is equivalent to choosing Text Caps SmallCaps.


Syntax
SmallCaps()

Return Value
1  (TRUE) if the attribute was set.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
WHILE "" = CurShade$()
    UserControl("Select the text to modify, then choose Resume...")
WEND
SmallCaps()
END FUNCTION

See also:

    LowerCase
    UpperCase


ΓòÉΓòÉΓòÉ 406. Spacing ΓòÉΓòÉΓòÉ

This function sets line spacing for the current paragraph or selected
paragraphs. This function is equivalent to choosing Text Spacing.


Syntax
Spacing(Amount)
Amount is the new spacing to set. The Amount parameter determines fixed line
spacing according to the following list:
    SpaceStyle (0) - Use the line spacing specified in the paragraph style
    SpaceSingle (-1) - Use single spacing
    SpaceOneHalf (-2) - Use 1 1/2 line spacing
    SpaceDouble (-3) - Use double spacing
To set custom line spacing, the Amount parameter should be a positive integer
representing line spacing in twips. To determine twips from points, multiply
the point size by 20.

To display the Spacing dialog box and allow the user to determine the new
spacing: Spacing

Return Value
1  (TRUE) if the line spacing was successfully changed.
0  (UserCancel) if the user canceled the function.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
Spacing(-2)
END FUNCTION

See also:

    Center
    FontChange
    Justify
    LeftAlign
    NormalText
    RightAlign


ΓòÉΓòÉΓòÉ 407. SpecialEffects ΓòÉΓòÉΓòÉ

This function sets special effects for selected text or for all following text
if no text is selected. This function is equivalent to choosing Text Special
Effects.


Syntax
SpecialEffects(Which, OverStrikeChar)
Which is a flag representing the special effects to use and can be one of the
following:
    Superscript (64) - Superscript text
    Subscript (128) - Subscript text
    DoubleUnderline (256) - Double underline text
    Strikethrough (512) - Strikethrough text
    Overstrike (1024) - Overstrike text with character given in OverStrike
    parameter
OverStrikeChar is the character used to overstrike the text. The Overstrike
value in the Which parameter must also be set.
More than one special effect can be chosen by adding the values for the desired
effects together.

To display the Special Effects dialog box and allow the user to determine
special effects settings: SpecialEffects

Return Value
1  (TRUE) if the special effects were applied.
0  (UserCancel) if the user canceled the function.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
SpecialEffects(Superscript + DoubleUnderline, "")
END FUNCTION

See also:

    NormalText
    Underline
    WordUnderline


ΓòÉΓòÉΓòÉ 408. SpellCheck ΓòÉΓòÉΓòÉ

This function allows you to check the spelling of words or documents. This
function is equivalent to choosing Tools Spell Check.


A macro must be edited to insert this non-recordable function.

Syntax
SpellCheck(Options)
Options is a flag representing the options to use for the spell check, and can
be one or more of the following:
    SpellBegin (1) - Starts the spell checking from the beginning of the
    document.
    CurrentStream (2) - Spell checks only the current stream. Do not set this
    flag if you want all streams to be spell checked.
    NoDoubleWord (4) - Ignores repeated words.
    IgnoreNums (8) - Ignores words containing numbers.
    IgnoreInitCaps (16) - Checks the spelling of words that do not begin with a
    capital letter.
    TurboCheck (32) - Speeds up the spell checking by only checking the
    documents that have been flagged as changed since the last spell check.
    SpellAlt (64) - Checks for alternate spelling entered by the user.

To display the Spell Check dialog box and allow the user to select the
parameters: SpellCheck

Return Value
1  (TRUE) if the spell check was done.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the spell check could not be done.

Example
FUNCTION Example()
SpellCheck(1)
END FUNCTION

See also:

    ChangeLanguage
    Thesaurus




ΓòÉΓòÉΓòÉ 409. StandardView ΓòÉΓòÉΓòÉ

This function changes the current view level to standard view. This function is
equivalent to choosing View Standard.


Syntax
StandardView()

Return Value
This function returns 1.

Example
FUNCTION Example()
StandardView()
END FUNCTION

See also:

    CustomView
    EnlargedView
    FacingView
    FullPageView
    GetViewLevel
    LayoutMode


ΓòÉΓòÉΓòÉ 410. StatusBarMsg ΓòÉΓòÉΓòÉ

This function displays a message in the Ami Pro status bar. The macro does not
pause. The message can be reset by calling this function with the null string
("") as its parameter.


Syntax
StatusBarMsg(Message)
Message is the string of text to be displayed in the program's status bar. If
the null string ("") is sent, the default Ami Pro status bar is restored.

Return Value
1  (TRUE) if the message was displayed.
-2  (GeneralFailure) if the message could not be displayed.

Example
FUNCTION Example()
IgnoreKeyboard(1)
HourGlass(1)
StatusBarMsg("Importing graphic file...")
ImportPicture("Bitmap", "C:\AMIPRO\ICONS\123W.BMP", ".BMP", 0)
StatusBarMsg("")
HourGlass(0)
IgnoreKeyboard(0)
END FUNCTION

See also:

    AnswerMsgBox
    HourGlass
    IgnoreKeyboard
    KeyInterrupt
    Messages


ΓòÉΓòÉΓòÉ 411. strcat ΓòÉΓòÉΓòÉ

This function concatenates strings together to make a longer string. Any number
of strings can be appended together at a time.


Syntax
strcat$(Text1, Text2[, Text3...])
Text1 is a string to which Text2 is appended.
Text2 is a string which is appended to Text1.
Text3 is a string which is appended to Text1 and Text2.

Return Value
This function returns the new string.

Example
FUNCTION Example()
MacFile = GetRunningMacroFile$()
SetDlgCallBack(50, "{MacFile}!Message1")
Box = DialogBox(".", "ExampleBox")
IF Box = -1
    Message("Could not find dialog box!")
    EXIT FUNCTION
ELSEIF Box = 0
    EXIT FUNCTION
ENDIF
TYPE(GetDialogField$(8002))
END FUNCTION

FUNCTION Message1(hdlg, id, text)
Name = GetDlgItemText(hdlg, 8000)
Message("The contents of the first box are {Name}.")
Message("We will now fill the second box with the inverse of {Name}.")
FOR I = len(Name) to 1 step -1
    Name2 = strcat$(Name2, MID$(Name, I, 1))
NEXT
SetDlgItemText(hdlg, 8002, Name2)
END FUNCTION

DIALOG ExampleBox
-2134376448 8 106 38 160 54 "" "" "Sample Dialog Box"
FONT 6 "Helv"
50 6 62 12 8000 1350631552 "edit" "" 0
4 6 44 10 1000 1342177280 "static" "Your Name:" 0
50 20 62 12 1003 1342177287 "static" "" 0
4 22 44 10 1002 1342177280 "static" "Reversed:" 0
52 22 58 8 8002 1342177280 "static" "" 0
116 4 40 14 1 1342242817 "button" "OK" 0
116 20 40 14 2 1342242816 "button" "Cancel" 0
100 36 56 14 50 1342242816 "button" "&Run Example..." 0
END DIALOG

See also:

    ASC
    FormatNum$
    LCASE$
    LEN
    MID$
    strchr
    strfield$
    UCASE$


ΓòÉΓòÉΓòÉ 412. strchr ΓòÉΓòÉΓòÉ

This function searches the specified string for a character. It returns the
location of the character within the string.


Syntax
strchr(Offset, Text, Char)
Offset is the location in the string to begin searching. Offset is one based.
To search from the beginning of the string, use an offset of 1.
Text is a string that is searched for a specific character.
Char is the first character to be searched for.

Return Value
The number of characters into the string at which the desired character was
found.
-1 if the desired character is not found in the string, the function returns.

Example
FUNCTION Example()
String = Query$("Enter the string:")
Offset = 0
Char = Query$("What char to search for?")
Position = Strchr(Offset, String, Char)
Message(Position)
END FUNCTION

See also:

    ASC
    CHR$
    FormatNum$
    Instr
    LCASE$
    Left$
    LEN
    MID$
    Right$
    strcat$
    strfield$
    UCASE$


ΓòÉΓòÉΓòÉ 413. strfield ΓòÉΓòÉΓòÉ

This function is used to extract individual fields from a field delimited
string. The function assumes a record format where variable length fields are
separated from each other with a unique character.


Syntax
strfield$(Text, FieldNumber, Separator)
Text is the string from which the field is extracted.
FieldNumber is the number of the field to be extracted (1 = first field).
Separator is the character which separates the fields.

Return Value
This function returns the extracted field.
 -1 if there are not enough fields in the string.
The null string ("") if the desired field is empty.

Example
FUNCTION Example()
LayoutMode()
IF not IsFrameSelected()
    Pos = CursorPosition$()
    x = strfield$(Pos, 1, ",")
    y = strfield$(Pos, 2, ",")
    AddFrame(x, y, (x + 1440), (y - 1440))
ENDIF
Type("[enter]")
END FUNCTION

See also:

    ASC
    CHR$
    strcat$
    strchr
    LCASE$
    UCASE$
    MID$
    LEN
    FormatNum$



ΓòÉΓòÉΓòÉ 414. StyleManagement ΓòÉΓòÉΓòÉ

This function allows the user to view the Style Management dialog box and
assign function keys to paragraph styles. This function is equivalent to
choosing Style Style Management.


This function does not manage paragraph styles automatically.

Syntax
StyleManagement()

Return Value
1  (TRUE) if the changes were accepted.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
StyleManagement()
END FUNCTION

See also:

    ModifyStyle
    SaveAsNewStyle


ΓòÉΓòÉΓòÉ 415. TableGetRange ΓòÉΓòÉΓòÉ

This function returns the starting and ending rows selected if the insertion
point is in a table. If a single cell or no cell is selected, the starting row
equals the ending row. If you are not in a table, the passed variables are not
changed.


Syntax
TableGetRange(&StartRow, &StartCol, &EndRow, &EndCol)
&StartRow contains the row the insertion point is in.
&StartCol contains the column the insertion point is in.
&EndRow contains the last selected row.
&EndCol contains the last selected column.
If a range is selected in the table, StartRow and StartCol are different from
EndRow and EndCol.
If you are not in the  tables mode, StartRow, StartCol, EndRow, and EndCol are
not changed.

Return Value
 1  (TRUE) if you are in  tables  mode, the variables are updated.
 0  (FALSE) if you are not in  tables mode.

Example
FUNCTION Example()
DEFSTR StartRow, StartCol, EndRow, EndCol;
Tables(1, TRUE, 4, 10)
TableLayout(2, Off, 1440, 0, 1440, 0, On, On, 9, Off, On, Off)
WHILE StartRow != 2
TYPE("[Right]")
TableGetRange(&StartRow, &StartCol, &EndRow, &EndCol)
WEND
TYPE("[SHIFTRight][SHIFTRight]")
ConnectCells()
TableLines(AllSides, 0, 0, OnePoint, 0)
END FUNCTION

See also:

    TableLayout
    Tables


ΓòÉΓòÉΓòÉ 416. TableLayout ΓòÉΓòÉΓòÉ

This function sets the layout of an existing table. This function is equivalent
to choosing Table Modify Table Layout.


Syntax
TableLayout(2, AutoHeight, ColWidth, 0, RowHeight, 0, Center, LineAround,
LineStyle, HonorProtect, SpanPages, DisableMouse)
AutoHeight is a flag indicating whether the automatic row height option is
enabled. The AutoHeight parameter should be set to 1 (On) if the height of rows
should be allowed to grow automatically, or 0 (Off) if the row height should be
fixed.
ColWidth is the default width of the columns in twips (1 inch = 1440 twips).
RowHeight is the default height of the rows in twips (1 inch = 1440 twips). If
AutoHeight=On, RowHeight is ignored but must be set.
Center is a flag indicating whether a page table should be centered on the page
and can be one of the following:
    1 (On) if the table should be centered on the page.
    0 (Off) if the table is not to be centered on the page.
If the table is in a frame, this parameter is ignored, but should still be set.
LineAround is a flag indicating whether there should be a line around the
table, and may be one of the following:
    1 (On) if a line should be drawn around the table.
    0 (Off) if no line should be drawn around the table.
LineStyle is the paragraph style to use for the line around the table and may
be one of the following:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rules
    DoubleTwoPoint (9) - Parallel two point rules
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
If LineAround=0, LineStyle is ignored but must be set.
HonorProtect is a flag indicating whether protection should be honored in the
table and may be one of the following:
    1 (On) if cells marked as protected should not be editable.
    0 (Off) if protected cells can be edited.
SpanPages is a flag indicating whether data in a cell should continue to the
next page without moving the entire row to the next page. The AutoHeight
parameter must also be set to 1 if SpanPages is set to 1.
    1 (On) - If rows should span pages
    0 (Off) - If rows should not span pages
DisableMouse is a flag indicating whether the mouse can change the size of rows
and columns.
    1 (On) if the mouse should be disabled
    0 (Off) if the mouse should be enabled

To display the Table Layout dialog box and allow the user to set the table
layout: TableLayout

Return Value
1  (TRUE) if the table layout was changed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the layout could not be changed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
DEFSTR StartRow, StartCol, EndRow, EndCol;
Tables(1, TRUE, 4, 10)
TableLayout(2, Off, 1440, 0, 1440, 0, On, On, 9, Off, On, Off)
WHILE StartRow != 2
TYPE("[Right]")
TableGetRange(&StartRow, &StartCol, &EndRow, &EndCol)
WEND
TYPE("[SHIFTRight][SHIFTRight]")
ConnectCells()
TableLines(AllSides, 0, 0, OnePoint, 0)
END FUNCTION

See also:

    ProtectCells
    TableLines
    Tables


ΓòÉΓòÉΓòÉ 417. TableLines ΓòÉΓòÉΓòÉ

This function sets the line and color options for a cell or group of cells.
This function is equivalent to choosing Table Lines & Color.


Syntax
TableLines(LineOn, LineOff, NoChange, LineStyle, ShadeType)
LineOn is a flag indicating which sides of the cell should have the new lines
and colors and may be one or more of the following:
    AllSides (1) - All sides of the cell
    Outline (2) - The outline of the cell
    LeftSide (4) - The left side of the cell
    RightSide (8) - The right side of the cell
    TopSide (16) - The top side of the cell
    BottomSide (32) - The bottom side of the cell
    CellShade (64) - The shading of the cell
Multiple sides of the cell can be specified by adding the individual values
together.
LineOff is a flag indicating which sides of the cell should not have lines or
colors and may be one or more of the following:
    AllSides (1) - All sides of the cell
    Outline (2) - The outline of the cell
    LeftSide (4) - The left side of the cell
    RightSide (8) - The right side of the cell
    TopSide (16) - The top side of the cell
    BottomSide (32) - The bottom side of the cell
    CellShade (64) - The shading of the cell
Multiple sides of the cell can be specified by adding the individual values
together.
NoChange is a flag indicating which sides of the cell should remain the same
and may be one or more of the following:
    None (0) - No sides of the cell
    AllSides (1) - All sides of the cell
    Outline (2) - The outline of the cell
    LeftSide (4) - The left side of the cell
    RightSide (8) - The right side of the cell
    TopSide (16) - The top side of the cell
    BottomSide (32) - The bottom side of the cell
    CellShade (64) - The shading of the cell
Multiple sides of the cell can be specified by adding the individual values
together.
The LineOn, LineOff, and NoChange parameters are equivalent to choosing check
box states for each of the sides of the cell. Using the menu function, a
checked box indicates that the new lines and colors should be applied to the
element indicated by the box. An unchecked box indicates that no lines and
colors should be applied to an element. A grayed box indicates that lines or
colors are already applied to the element and that they should not be changed
from what they already are.
LineStyle is a number representing the desired line paragraph style and may be
one of the following:
    Hairline (1) - Hairline
    OnePoint (2) - One point rule
    TwoPoint (3) - Two point rule
    ThreePoint (4) - Three point rule
    FourPoint (5) - Four point rule
    FivePoint (6) - Five point rule
    SixPoint (7) - Six point rule
    DoubleOnePoint (8) - Parallel one point rules
    DoubleTwoPoint (9) - Parallel two point rules
    ThreeLines (10) - Hairline above and below a two point rule
    HairBelow (11) - Hairline below a three point rule
    HairAbove (12) - Hairline above a three point rule
ShadeType is a number representing the desired shading type and may be one of
the following:
    BlackShade (1) - Black background
    SeventyFiveShade (2) - 75% black shading
    FiftyShade (3) - 50% black shading
    TwentyFiveShade (4) - 25% black shading
    TenShade (5) - 10% black shading
    BlueShade (6) - Blue background
    RedShade (7) - Red background
    MagentaShade (8) - Purple background
    GreenShade (9) - Green background
    YellowShade (10) - Yellow background
    CyanShade (11) - Light blue background
    WhiteShade (12) - White background
If no shading should be applied to the cell(s), this parameter should be set
but the value of the parameter is ignored.

To display the Lines dialog box and allow the user to set the table line
options: TableLines

Return Value
1  (TRUE) if the cell lines and colors were changed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the lines could not be changed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
DEFSTR StartRow, StartCol, EndRow, EndCol;
Tables(1, TRUE, 4, 10)
TableLayout(2, Off, 1440, 0, 1440, 0, On, On, 9, Off, On, Off)
WHILE StartRow != 2
TYPE("[Right]")
TableGetRange(&StartRow, &StartCol, &EndRow, &EndCol)
WEND
TYPE("[SHIFTRight][SHIFTRight]")
ConnectCells()
TableLines(AllSides, 0, 0, OnePoint, 0)
END FUNCTION

See also:

    TableLayout
    Tables


ΓòÉΓòÉΓòÉ 418. Tables ΓòÉΓòÉΓòÉ

This function creates a table with the specified parameters. This function is
equivalent to choosing Tools Tables.


Syntax
Tables(Which, AutoHeight[, ColWidth, 0, RowHeight, 0, Center, LineAround,
LineStyle, HonorProtect, SpanPages], NumCols, NumRows)
Which is a flag indicating what to do with this function and can be one of the
following:
    (1) - Creates only the table
    (3) - Creates the table and includes the table layout information
AutoHeight is set if the height of the rows in the new table should be auto
height. This function can be a 1 (On), or a 0 (Off).
ColWidth is the width of the columns to create, in twips.
RowHeight is the height of the rows to create, in twips.
This parameter is ignored if the AutoHeight parameter is set to 1.
Center is set if you want the table to be centered between the margins and may
be a 1 (On) or a 0 (Off).
If this table is being placed in a frame, this parameter is ignored.
LineAround is used if you want a line to be placed around the table and may be
a 1 (On) or a 0 (Off).
LineStyle is the style of the line to be placed around the table if the
LineAround parameter is set to 1.
HonorProtect is set if you want honor protection set inside the table. It can
be a 1 (On) or a 0 (Off).
SpanPages is set if you want rows to span pages (On) or if you want rows to be
retained separately over page breaks (Off).
NumCols is the number of columns to place in this table.
NumRows is the number of rows to place in this table.

Return Value
1  (TRUE) if the table was created.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the table could not be created.

Example
FUNCTION Example()
DEFSTR StartRow, StartCol, EndRow, EndCol;
Tables(1, TRUE, 4, 10)
TableLayout(2, Off, 1440, 0, 1440, 0, On, On, 9, Off, On, Off)
WHILE StartRow != 2
TYPE("[Right]")
TableGetRange(&StartRow, &StartCol, &EndRow, &EndCol)
WEND
TYPE("[SHIFTRight][SHIFTRight]")
ConnectCells()
TableLines(AllSides, 0, 0, OnePoint, 0)
END FUNCTION

See also:

    AddFrame
    TableLayout
    TableLines




ΓòÉΓòÉΓòÉ 419. TabRulerInsert ΓòÉΓòÉΓòÉ

This function inserts a tab ruler. This function is equivalent to choosing Page
Ruler Insert.


Syntax
TabRulerInsert()

Return Value
1  (TRUE) if the tab ruler was inserted.
If this function is called when Page/Ruler/Insert is grayed, the macro
terminates and displays an error message.

Example
FUNCTION Example()
TabRulerInsert()
END FUNCTION

See also:

    ModifyLayout
    TabRulerRemove



ΓòÉΓòÉΓòÉ 420. TabRulerRemove ΓòÉΓòÉΓòÉ

This function removes a tab ruler. This function is equivalent to choosing Page
Ruler Remove.


Syntax
TabRulerRemove()

Return Value
1  (TRUE) if the tab ruler was removed.
If this function is called when Page Ruler Remove is grayed, the macro
terminates and displays an error message.

Example
FUNCTION Example()
TabRulerRemove()
END FUNCTION

See also:

    ModifyLayout
    TabRulerInsert


ΓòÉΓòÉΓòÉ 421. Thesaurus ΓòÉΓòÉΓòÉ

This function displays the Thesaurus dialog box and searches for the selected
word in the Thesaurus. This function is equivalent to choosing Tools Thesaurus.
This function does not automatically use the thesaurus functions.


Syntax
Thesaurus()

Return Value
This function returns 0.

Example
FUNCTION Example()
Thesaurus()
END FUNCTION

See also:

    SpellCheck


ΓòÉΓòÉΓòÉ 422. TileWindow ΓòÉΓòÉΓòÉ

This function allows you to tile windows without overlapping them. This
function is equivalent to choosing Window Tile.


Syntax
TileWindow()

Return Value
This function does not return a value.

Example
FUNCTION Example()
Text = UCASE$(Left$(Query$("What action to take (Tile, Cascade, New, Select) on
MDI Windows?"), 1))
SWITCH Text
CASE "T"
TileWindow()
CASE "C"
CascadeWindow()
CASE "N"
NewWindow()
CASE "S"
SelectWindow(Query$("Name of window to select (Name must match EXACTLY)?"))
default
Message("Only the proposed options are available.")
ENDSWITCH
END FUNCTION

See also:

    CascadeWindow
    NewWindow
    NextWindow
    SelectWindow



ΓòÉΓòÉΓòÉ 423. TOCOptions ΓòÉΓòÉΓòÉ

This function sets the options for a generated table of contents for the
current document. This function is equivalent to choosing File Master Document
and choosing TOC Options. It is also equivalent to choosing Tools Generate TOC
and choosing TOC Options.


Syntax
TOCOptions(Style, Separator, Flag[, Style, Separator, Flag...])
Style is the name of the paragraph style.
Separator is the character that separates the text from the page number. The
separator that can be used is dependent on the Flag parameter and can be one of
the following:
    ("") - None
    (".") - Dot
    ("-") - Dash
    ("_") - Underline
    (",") - Comma
Flag can be either page numbers, or right alignment and page numbers.
    (1) - Use page numbers
    (2) - Use right alignment (must combine with Use page numbers)
The rules for the Flag parameter:
    If both page numbers and right align are used, the separator can be none,
    dot, dash or underline.
    If only page numbers are used, the separator can be only none or comma.
    If right align is used, it must be combined with the value for Use page
    numbers.
    If page numbers are not used, the separator must be none.

Return Value
This function returns 1.

Example
FUNCTION Example()
TOCOptions("Title" "." 3 "Subhead" ", " 1 )
END FUNCTION

See also:

    Generate
    SetTOCFile


ΓòÉΓòÉΓòÉ 424. ToggleCleanScreen ΓòÉΓòÉΓòÉ

This functions turns on Clean Screen mode if it is not already on. If Clean
Screen mode is on, then it turns off. This function is equivalent to choosing
View Hide Clean Screen or View Show Clean Screen.


Syntax
ToggleCleanScreen()

Return Value
This function returns 1.

Example
FUNCTION Example()
CleanScreenOptions(112)  ' Display the scroll bars and return icon
ToggleCleanScreen()
END FUNCTION

See also:

    CleanScreenOptions


ΓòÉΓòÉΓòÉ 425. ToggleIconBar ΓòÉΓòÉΓòÉ

This function shows or hides the set of SmartIcons. If the SmartIcon set is
displayed, it is hidden. If the SmartIcon set is hidden, it is displayed. This
function is equivalent to choosing View Hide SmartIcons or View Show
SmartIcons.


Syntax
ToggleIconBar()

Return Value
1  (TRUE) if the icon bar toggled.
0  (NoAction) if no action was taken.

Example
FUNCTION Example()
ToggleIconBar()
END FUNCTION

See also:

    HideIconBar
    IconBottom
    IconCustomize
    IconFloating
    IconLeft
    IconRight
    IconTop
    ShowIconBar
    ShowIconBar
    ToggleTabRuler
    ViewPreferences


ΓòÉΓòÉΓòÉ 426. ToggleTabRuler ΓòÉΓòÉΓòÉ

This function shows or hides the tab ruler. If the tab ruler is displayed, it
is hidden. If the tab ruler is hidden, it is displayed. This function is
equivalent to choosing View Hide Ruler or View Show Ruler.


Syntax
ToggleTabRuler()

Return Value
This function returns 1.

Example
FUNCTION Example()
ToggleTabRuler()
END FUNCTION

See also:

    HideTabRuler
    ShowTabRuler
    ToggleIconBar
    ViewPreferences


ΓòÉΓòÉΓòÉ 427. TopOfFile ΓòÉΓòÉΓòÉ

This function scrolls the document to the beginning of the file without moving
the insertion point. This function is equivalent to dragging the slider box on
the vertical scroll bar to the extreme top using the mouse.


Syntax
TopOfFile()

Return Value
This function returns 0.

Example
FUNCTION Example()
Action = Query$("Move to (T)op of file, or (E)nd of file?")
Action = UCASE$(Left$(Action, 1))
SWITCH Action
CASE "T"
Message(TopOfFile())
CASE "E"
Message(EndOfFile())
default
Message("""T"" or ""E"" will do just fine, please.")
ENDSWITCH
END FUNCTION

See also:

    CharLeft
    CharRight
    EndOfFile
    LeftEdge
    LineDown
    LineUp
    RightEdge
    ScreenDown
    ScreenLeft
    ScreenRight
    ScreenUp


ΓòÉΓòÉΓòÉ 428. Truncate ΓòÉΓòÉΓòÉ

This function removes any fractional part of a number.


Syntax
Truncate(Value)
Value is the number to be evaluated.

Return Value
The integer portion of the passed value.

Example
FUNCTION Example()
Number = 123.4455682
Message(Truncate(Number))
END FUNCTION

See also:

    IsNumeric
    Mod
    Round


ΓòÉΓòÉΓòÉ 429. TYPE ΓòÉΓòÉΓòÉ

This function inserts information into the current Ami Pro document. You can
also use it to move the insertion point or activate a function key.


Ami Pro converts the Text into ANSI/UNICode characters when you compile the
macro. When you playback the macro, Ami Pro converts the ANSI/UNICode
characters to code pages. Ami Pro displays any invalid characters as asterisks.

Syntax
TYPE(Text)
Text is the string to insert into the current Ami Pro document.
Text can be any keyboard character. Any attributes or variables within the
string are not typed into the document. To insert a left curly brace, type two
curly braces ({{). To insert a left square brace, type two square braces ([[).
To insert a double quote mark, type two double quote marks (""). Text can
contain a variable name. If a variable name is used, enclose it in curly braces
({}) so that it can be recognized as a variable name.
Text can also contain an insertion point movement or function key. To type a
key, surround its name with square braces. An insertion point movement or
function key can include the words CTRL, SHIFT or ALT to indicate a shifted
state. The following key names can be used:
    [Home] - Home Key
    [End] - End Key
    [PgUp] - Page Up Key
    [PgDn] - Page Down Key
    [Ins] - Insert Key
    [Del] - Delete Key
    [Backspace] - Backspace Key
    [Enter] - Enter or Return Key
    [Tab] - Tab Key
    [ESC] - Escape Key
    [Up] - Up Arrow Key
    [Down] - Down Arrow Key
    [Left] - Left Arrow Key
    [Right] - Right Arrow Key
    [F1] - [F12] - Function Keys F1 through F12

Return Value
This function does not return a value.

Example
FUNCTION Example()
TYPE("NumberCharacter[Enter]")
FOR I = 1 to 255
    Char = CHR$(I)
    TYPE("{I}={Char}[Enter]")
NEXT
END FUNCTION

See also:

    CurChar$
    CurShade$
    CurWord$
    FormatNum$




ΓòÉΓòÉΓòÉ 430. TypeOver ΓòÉΓòÉΓòÉ

This function turns Typeover mode on or off. It acts as a toggle, turning off
the Typeover mode if it is currently on or turning on the Typeover mode if it
is currently off. This function is equivalent to pressing the Insert key.


Syntax
TypeOver()

Return Value
1  (TRUE) if the typeover status was changed.
0  (NoAction) if no action was taken.

Example
FUNCTION Example()
TypeOver()
END FUNCTION

See also:

    TYPE


ΓòÉΓòÉΓòÉ 431. UCASE ΓòÉΓòÉΓòÉ

This function changes lowercase letters in the source string to upper case
letters and returns the resulting string. It does not change punctuation or
numbers.


Syntax
UCASE$(Text)
Text is the string which changes to upper case.

Return Value
The string with all uppercase letters.

Example
FUNCTION Example()
Name = UCASE$(Query$("What is your name?"))
Message(Name)
END FUNCTION

See also:

    ASC
    CHR$
    FormatNum$
    LCASE$
    LEN
    MID$
    strcat$
    strfield$


ΓòÉΓòÉΓòÉ 432. Underline ΓòÉΓòÉΓòÉ

This function sets the underline attribute for selected text or for all
following text if no text is selected. It acts as a toggle, turning off the
attribute if it is currently on or turning on the attribute if it is currently
off. This function is equivalent to choosing Text Underline.


Syntax
Underline()

Return Value
0 if the underline attribute is toggled on and there are no attributes assigned
to the text.
4 if the underline attribute is toggled on and the bold attribute is already
assigned.
8 if the underline attribute is toggled on and the italic attribute is already
assigned.
16 if the underline attribute is toggled off.
32 if the underline attribute is toggled on and the word underline attribute is
already assigned.
The return values may be added together to identify the attributes that were
previously assigned.
-2  (GeneralFailure) if the attribute was not changed.

Example
FUNCTION Example()
text = Query$("Enter some text:")
New("_default.sty", 0, 0)      'open a new file
TYPE("{text}")
TYPE("[enter]")
TYPE("[ctrlhome][ctrlshiftend]")
Copy() 'copy text to clipboard
FOR I = 1 to 10
    Paste()   'paste text 10 times
NEXT
Message("The text will be shaded, bolded, italicized, underlined, and
centered.")
TYPE("[ctrlhome][ctrlshiftend]")
Bold()
Italic()
Underline()
Center()
TYPE("[ctrlhome]")
END FUNCTION

See also:

    Bold
    Italic
    NormalText
    WordUnderline


ΓòÉΓòÉΓòÉ 433. Undo ΓòÉΓòÉΓòÉ

This function undoes the previous editing function. This function is equivalent
to choosing Edit Undo.


Syntax
Undo()

Return Value
1  (TRUE) if the function was successfully undone.
0  (NoAction) if no action was taken.

Example
FUNCTION Example()
Undo()
END FUNCTION

See also:

    UserSetup


ΓòÉΓòÉΓòÉ 434. UpperCase ΓòÉΓòÉΓòÉ

This function sets upper case for selected text or for all following text if no
text is selected. It acts as a toggle, turning off upper case if it is
currently on or turning on upper case if it is currently off. It is the
equivalent to choosing Text Caps Upper Case.


Syntax
UpperCase()

Return Value
1  (TRUE) if the attribute was changed.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the attribute could not be changed.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
UpperCase()
END FUNCTION

See also:

    LowerCase
    SmallCaps


ΓòÉΓòÉΓòÉ 435. UserControl ΓòÉΓòÉΓòÉ

This function displays a modeless dialog box titled "Macro Pause" with the
specified prompt string and Resume, Cancel, and Help push buttons. The user can
click outside this dialog box to do any regular Ami Pro function. When the user
is done, he can click the Resume button to resume the macro or the Cancel
button to cancel the macro.


Press ALT+F6 to toggle between Ami Pro and the dialog box.

Syntax
UserControl(Prompt)
Prompt is a string passed as a prompt to the user. Ami Pro accepts a maximum of
80 characters. However, the number of characters that actually display depends
on the font used for dialog boxes.

Return Value
This function does not return a value. If the user selects Cancel, control
passes to the routine defined by the ONCANCEL statement.

Example
FUNCTION Example()
UserControl("Click Resume to bring up System Setup...")
ControlPanel
UserControl("Click Resume to shut down System Setup...")
AppClose("System Setup")
END FUNCTION

See also:

    Decide
    DialogBox
    IgnoreKeyboard
    KeyInterrupt
    Message
    Messages
    Using the ONCANCEL Statement
    Query$
    SingleStep



ΓòÉΓòÉΓòÉ 436. UserSetup ΓòÉΓòÉΓòÉ

This function sets defaults for using Ami Pro. This function is equivalent to
choosing Tools User Setup.


Syntax
UserSetup(UndoLevel, SaveTime, Options, Flag, UserName, UserInitials, Color,
LoadMacro, ExitMacro, MacroOptions, RecentFiles)
UndoLevel is the desired undo level (0-4).
SaveTime is the time between saves, in minutes. If the autosave function is on.
Options is the flag containing other default options. It is one of the
following values:
    NoUndo (0) - No level set is undone
    Undo1 (2) - Single undo level
    Undo2 (4) - Two levels undone
    Undo3 (8) - Three levels undone
    Undo4 (16) - Four levels undone
    (32) - Disable one-line Help
    (64) - Disable the Drag & Drop feature
    BackupOn (128) - Automatic Backup turned on
    TimedSaveOn (256) - Timed Save turned on
    (2048) - Disable warning messages
Flag is currently unused, and is set to 0.
UserName is the name of the user for the document locking function.
UserInitials is the initials of the user for note functions.
Color is the color for notes. It is one of the following values:
    White (16777215)
    Cyan (16776960)
    White (16777215)
    Cyan (16776960)
    Yellow (65535)
    Magenta (16711935)
    Green (65280)
    Red (255)
    Blue (16711680)
    Black (0)
LoadMacro is the name of the macro to run automatically when Ami Pro is loaded.
ExitMacro is the name of the macro to run automatically when Ami Pro is exited.
MacroOptions is the options for running the load and exit macros. It is one of
the following values:
    NoMacroRun (0) - Do not run the load macro or exit macro.
    MacroLoad (2) - Set the flag to run the macro given for LoadMacro when Ami
    Pro is loaded.
    MacroExit (4) - Set the flag to run the macro given for ExitMacro when Ami
    Pro is exited.
RecentFiles is the number of recent files to list on the File menu.

To display a dialog box to allow the user to select his defaults: UserSetup

Return Value
1  (TRUE) if the setup defaults were set.
0  (UserCancel) if the user canceled the function.

Example
FUNCTION Example()
UserSetup(4, 0, 0, 0, "Your Name", "YIN", 65535, "", "", 0, 0)
END FUNCTION

See also:

    LoadOptions
    SetBackPath
    SetDefOptions
    SetDocPath
    SetIconPath
    SetMacroPath
    SetStylePath
    UseWorkingDir
    ViewPreferences



ΓòÉΓòÉΓòÉ 437. UseWorkingDir ΓòÉΓòÉΓòÉ

This function determines whether to use the last directory you selected when a
file was opened or saved. This function is equivalent to choosing Tools User
Setup, choosing Paths, and selecting or deselecting Use working directory.


Syntax
UseWorkingDir(Flag)
Flag is one of the following:
    (1) - remembers the last directory used when opening or saving a file.
    (0) - doesn't remember the last directory used when opening or saving a
    file.
The directory used to open or save the next file is based on the default
document path defined in the Tools User Setup Paths Document text box when the
flag is set to zero. If the SetDocPath function is used, the working directory
path resets to the new path but the UseWorkingDir flag is still valid.

Return Value
This function returns 1.

Example
FUNCTION Example()
UseWorkingDirectory(1)
END FUNCTION

See also:

    SetDocPath
    UserSetup






ΓòÉΓòÉΓòÉ 438. UsingHelp ΓòÉΓòÉΓòÉ

This function displays the online Help for Ami Pro. This function is equivalent
to choosing Help Using Help. This function does not select a Help topic
automatically. Because Help displays in a separate window, further macro
functions that cause a repaint of the Ami Pro window force Ami Pro to replace
the Help window.


If this function is used, it should be the last function used in the macro.

Syntax
UsingHelp()
Return Value
1  (TRUE) if the Help window was displayed.
-2  (GeneralFailure) if the Help window could not be displayed for some other
reason.
-6  (NoMemory) if the function failed because of insufficient memory.

Example
FUNCTION Example()
UsingHelp()
END FUNCTION

See also:

    About
    Help
    HowDoIHelp
    MacroHelp



ΓòÉΓòÉΓòÉ 439. ViewPreferences ΓòÉΓòÉΓòÉ

This function sets display preferences for using Ami Pro. This function is
equivalent to choosing View View Preferences.


Syntax
ViewPreferences(Options, ViewLevel)
Options are the display preferences to use, and can be one or more of the
following:
    ColumnGuides (1) - Displays column guides.
    ColorMargin (2) - Displays margins in color.
    ShowPictures (4) - Displays pictures in layout mode.
    ShowTabs (8) - Displays tabs and returns.
    ShowMarks (64) - Displays marks.
    ShowGrid (128) - Displays gridlines in table mode.
    ShowRowCol (256) - Displays Row/Column headings in table mode.
    ShowVertRuler (512) - Displays vertical ruler in layout mode.
    ShowHorzScroll (1024) - Displays the horizontal scroll bar.
    ShowNotes (2048) - Displays note marks in layout mode.
    ShowOutlineButtons (16384) - Displays outline buttons in outline mode.
    To set multiple options, add the option values together before passing them
    to the function.
ViewLevel is the Custom View level to use for Custom View. The ViewLevel
parameter should be set to the desired view level for the Custom View level,
between 10% and 400%.
To show the Display Preferences dialog box and allow the user to select his
display preferences: ViewPreferences

Return Value
1  (TRUE) if the display preferences were successfully set.
0  (UserCancel) if the user canceled the function.
-2  (GeneralFailure) if the preferences could not be set.

Example
FUNCTION Example()
ViewPreferences((1 + 2 + 4 + 8 + 64 + 128 + 256 + 512 + 2048 + 16384 + 4096),
91)
END FUNCTION

See also:

    CleanScreenOptions
    SetDefOptions







ΓòÉΓòÉΓòÉ 440. WordUnderline ΓòÉΓòÉΓòÉ

This function sets word only underlining for selected text or for all following
text if no text is selected. It acts as a toggle, turning off word underline if
it is currently on and turning on word underline if it is currently off. This
function is equivalent to choosing Text Word Underline.


Syntax
WordUnderline()

Return Value
(0)  if the word underline is toggled on and there are no attributes assigned
to the text.
(4)  if the word underline attribute is toggled on and the bold attribute is
already assigned.
(8)  if the word underline attribute is toggled on and the italic attribute is
already assigned.
(16)  if the word underline attribute is toggled on and the underline attribute
is already assigned.
(32)  if the word underline attribute is toggled off.
(-2)  (GeneralFailure) if the attribute was not changed.
The return values may be added together to identify the attributes that were
previously assigned.

Example
FUNCTION Example()
text = Query$("Enter some text:")
New("_default.sty", 0, 0)      'open a new file
TYPE("{text}")
TYPE("[enter]")
TYPE("[ctrlhome][ctrlshiftend]")
Copy() 'copy text to clipboard
FOR I = 1 to 10
    Paste()   'paste text 10 times
NEXT
Message("The text will word underline only.")
TYPE("[ctrlhome][ctrlshiftend]")
WordUnderline()
TYPE("[ctrlhome]")
END FUNCTION

See also:

    Bold
    Italic
    NormalText
    Underline




ΓòÉΓòÉΓòÉ 441. WriteProfileString ΓòÉΓòÉΓòÉ

This function writes an entry into the amiuser3.ini file.


Syntax
WriteProfileString(App, Item, Value[, FileName)
App is the name of the section in the .INI file. If the null string ("") is
passed for this parameter, the [AmiPro] section is used.
Item is the name of the entry to be added/changed.
Value is the data to be added/changed in the .INI file.
FileName is the filename to modify. If this parameter is not used or is passed
the null string (""), the amiuser3.iniI file is used. If the full path is not
used, the file is assumed to be in the Windows subdirectory.
If the file does not exist, a new file is created and this entry is placed into
it.

Return Value
This function does not return a value.

Example
FUNCTION Example()
Name = GetProfileString$("AmiPro", "UserName", "amiuser3.ini")
FillEdit(8000, Name)
DIM Filters(10)
FOR I = 1 to 10
Filters(I) = strfield$(GetProfileString$("AmiPro", "application{I}",
"amiuser3.ini"), 1, ",")
FillList(Filters(I))
NEXT
FOR I = 1 to 10
FillEdit(9500, Filters(I))
NEXT
FillEdit(50, TRUE)
FillEdit(55, TRUE)
Box = DialogBox(".", "ExampleBox")
IF Box = -1
Message("Could not open dialog box; Exiting macro.")
EXIT FUNCTION
ELSEIF Box = 0
EXIT FUNCTION
ENDIF
Name2 = GetDialogField$(8000)
IF Name != Name2
IF Decide("Do you want to save your changes?")
WriteProfileString("AmiPro", "UserName", Name2, "amiuser3.ini")
ENDIF
ENDIF
END FUNCTION

DIALOG ExampleBox
-2134376448 14 104 36 198 90 "" "" "Sample Dialog Box"
FONT 6 "Helv"
4 6 42 10 1000 1342308352 "static" "&User Name:" 0
52 4 92 12 8000 1350631552 "edit" "" 0
4 24 34 8 1001 1342308352 "static" "&Filters:" 0
4 34 66 52 9000 1352728579 "listbox" "" 0
74 24 52 8 1002 1342308352 "static" "&More Filters:" 0
74 34 70 40 9500 1344339971 "combobox" "" 0
74 46 60 40 24 1342308359 "button" "Group Box #1" 0
78 58 50 10 50 1342242825 "button" "Radio #1" 0
78 70 50 10 51 1342177289 "button" "Radio #2" 0
138 46 56 40 25 1342308359 "button" "Group Box #2" 0
142 56 48 12 55 1342242819 "button" "Check #1" 0
142 68 48 12 56 1342177283 "button" "Check #2" 0
154 4 40 14 1 1342373889 "button" "OK" 0
154 20 40 14 2 1342373888 "button" "Cancel" 0
END DIALOG

See also:

    GetProfileString$


ΓòÉΓòÉΓòÉ 442. Ami Pro Macro Functions Grouped Alphabetically ΓòÉΓòÉΓòÉ

Macro Functions A
Macro Functions B
Macro Functions C
Macro Functions D
Macro Functions E
Macro Functions F
Macro Functions G
Macro Functions H
Macro Functions I
Macro Functions J - K
Macro Functions L
Macro Functions M
Macro Functions N - O
Macro Functions P - Q
Macro Functions R
Macro Functions S
Macro Functions T
Macro Functions U - Z


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Ami Pro Macro Functions Grouped by Menu


ΓòÉΓòÉΓòÉ 443. Macro Functions A ΓòÉΓòÉΓòÉ

About
ActivateApp
AddCascadeMenu
AddCascadeMenuItem
AddFrame
AddFrameDlg
AddMenu
AddMenuItem
AllocGlobalVar
AmiProIndirect
AnswerMsgBox
AppClose
AppGetAppCount
AppGetAppNames
AppGetWindowPos
AppHide
AppIsRunning
ApplyFormat
AppMaximize
AppMinimize
AppMove
AppRestore
AppSendMessage
AppSize
ArrayDelete
ArrayInsert
ArrayInsertByKey
ArraySearch
ArraySize
ArraySort
ASC
ASCIIOptions
Assign
AssignMacroToFile
AtEOF


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 444. Macro Functions B ΓòÉΓòÉΓòÉ

Beep
BinToBrackets
Bold
BracketsToBin
BringFrameToFront


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically



ΓòÉΓòÉΓòÉ 445. Macro Functions C ΓòÉΓòÉΓòÉ

CascadeWindow
Center
ChangeCascadeAction
ChangeIcons
ChangeLanguage
ChangeMenuAction
ChangeShortcutKey
CharLeft
CharRight
CheckMenuItem
CHR$
CleanScreenOptions
ConnectCells
Copy
CreateDataFile
CreateDescriptionFile
CreateStyle
CurChar$
CurShade$
CurWord$
CustomView
Cut


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically



ΓòÉΓòÉΓòÉ 446. Macro Functions D ΓòÉΓòÉΓòÉ

DateDiff
DDEAdvise
DDEExecute
DDEInitiate
DDELinks
DDEPoke
DDEReceive$
DDETerminate
DDEUnAdvise
Decide
DefineStyle
DeleteColumnRow
DeleteEntireTable
DeleteMenu
DeleteMenuItem
DialogBox
DlgClearControl
DlgClose
DlgEnableControl
DlgGetListBoxCount
DlgGetListBoxLines
DlgHideControl
DlgKeyInterrupt
DlgLimitText
DlgSetCaption
DLLCall
DLLFreeLib
DLLLoadLib
DocInfo
DocInfoFields
DOSchdir
DOSCopyFile
DOSDelFile
DOSGetEnv$
DOSGetFileAttr
DOSmkdir
DOSRename
DOSrmdir
DOSSetFileAttr
DraftMode


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically



ΓòÉΓòÉΓòÉ 447. Macro Functions E ΓòÉΓòÉΓòÉ

EditFormula
ElevatorLeftRight
ElevatorUpDown
EndOfFile
EnlargedView
Equations
EvalField
Exec


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 448. Macro Functions F ΓòÉΓòÉΓòÉ

FacingView
FastFormat
fclose
fgets$
FieldAdd
FieldAuto
FieldCommand
FieldEvaluate
FieldLock
FieldNext/FieldPrev
FieldRemove
FieldToggleDisplay
FieldUpdate
FieldUpdateAll
FileChanged
FileClose
FileManagement
FileOpen
FilePrint
FillEdit
FillList
FindFirst$
FindNext$
FindReplace
FontChange
FontFaceChange
FontPointSizeChange
FontRevert
Footnotes
fopen
FormatDate$
FormatNum$
FormatSeq$
FormatTime$
fputs
FrameLayout
FrameModBorders
FrameModColumns
FrameModFinish
FrameModInit
FrameModLines
FrameModType
fread
FreeGlobalVar
fseek
ftell
FullPageView
fwrite


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 449. Macro Functions G ΓòÉΓòÉΓòÉ

Generate
GetAmiDirectory$
GetBackPath$
GetBookMarkCount
GetBookMarkNames
GetBookMarkPage
GetCurFontInfo
GetCurFrameBorders
GetCurFrameLines
GetCurFrameType
GetCurrentDir$
GetDialogField$
GetDlgItem
GetDlgItemText
GetDocInfo$
GetDocInfoKeywords$
GetDocPath$
GetDocVar
GetFmtPageStr$
GetGlobalArray$
GetGlobalVar$
GetGlobalVarCount
GetGlobalVarNames
GetHomeDirectory$
GetIconPalette
GetLayoutLeftLines
GetLayoutPageSize
GetLayoutParameters
GetLayoutType
GetMacPath$
GetMarkText$
GetMasterFiles
GetMasterFilesCount
GetMode
GetOpenFileCount
GetOpenFileName$
GetOpenFileNames
GetPageNo
GetPowerFieldCount
GetPowerFieldPage
GetPowerFields
GetProfileString$
GetRunningMacroFile$
GetRunningMacroName$
GetSpecialEffects$
GetStyleCount
GetStyleName$
GetStyleNames
GetStylePath$
GetTextBeforeCursor$
GetTime
GetViewLevel
GetViewPrefLevel
GetViewPrefOpts
Glossary
GlossaryAdd
GlossaryClose
GlossaryLookup
GlossaryOpen
GlossSet
GoToAgain
GoToCmd
GoToPowerField
GrayMenuItem


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 450. Macro Functions H ΓòÉΓòÉΓòÉ

HeaderFooter
Help
HideIconBar
HideTabRuler
HourGlass
HowDoIHelp


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 451. Macro Functions I ΓòÉΓòÉΓòÉ

IconBottom
IconCustomize
IconFloating
IconLeft
IconRight
IconTop
IgnoreKeyboard
ImageProcessing
ImportExport
ImportPicture
Indent
IndentAll
IndentFirst
IndentRest
InsertBullet
InsertCascadeMenu
InsertCascadeMenuItem
InsertColumnRow
InsertDate
InsertDocInfo
InsertDocInfoField
InsertLayout
InsertMenu
InsertMenuItem
InsertMerge
InsertMergeField
InsertNote
InsertVariable
Instr
IsFrameSelected
IsNumeric
Italic


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically



ΓòÉΓòÉΓòÉ 452. Macro Functions J - K ΓòÉΓòÉΓòÉ

Justify
KeyInterrupt


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically



ΓòÉΓòÉΓòÉ 453. Macro Functions L ΓòÉΓòÉΓòÉ

LayoutMode
LCASE$
LeaderDots
LeaderHyphs
LeaderLines
LeaderNone
Left$
LeftAlign
LeftEdge
LEN
LineDown
LineNumber
LineUp
LoadOptions
LowerCase


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 454. Macro Functions M ΓòÉΓòÉΓòÉ

MacroEdit
MacroHelp
MacroOptions
MacroPlay
ManualFrame
MarkBookMark
MarkIndexWord
MarkTOCEntry
MasterDoc
Maximize
Merge
MergeAction
MergeMacro
MergeToFile
Message
Messages
MID$
Minimize
Mod
ModifyAlignment
ModifyBreaks
ModifyEffects
ModifyFont
ModifyLayout
ModifyLines
ModifyReflow
ModifySelect
ModifySpacing
ModifyStyle
ModifyTable
ModLayoutFinish
ModLayoutInit
ModLayoutLeftFooter
ModLayoutLeftHeader
ModLayoutLeftLines
ModLayoutLeftPage
ModLayoutPageSize
ModLayoutRightFooter
ModLayoutRightHeader
ModLayoutRightLines
ModLayoutRightPage
MouseInterrupt


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 455. Macro Functions N - O ΓòÉΓòÉΓòÉ

New
NewWindow
NextWindow
NoHyphenation
NormalText
Notes
Now
OnKey
OpenDataFile
OpenMergeFile
OpenPreviousFile
OutlineLevels
OutlineMode
OutlineStyle


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically



ΓòÉΓòÉΓòÉ 456. Macro Functions P - Q ΓòÉΓòÉΓòÉ

PageBreak
PageDown
PageNumber
PageUp
Paste
Pause
PhysicalToLogical
PrintEnvelope
PrintOptions
PrintSetup
ProtectCells
Query$
QuickAddCol
QuickAddRow


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 457. Macro Functions R ΓòÉΓòÉΓòÉ

ReadMail
RecClose
RecFieldCount
RecFieldName$
RecGetField
RecNextRec
RecOpen
RemoveLayout
RenameDocInfoField
RenameMenuItem
Replace
Restore
Revert
RevertLayout
ReviewRevisions
RevisionInsertion
RevisionMarking
RevisionMarkOpts
Right$
RightAlign
RightEdge
Round
RunLater


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 458. Macro Functions S ΓòÉΓòÉΓòÉ

Save
SaveAs
SaveAsNewStyle
ScreenDown
ScreenLeft
ScreenRight
ScreenUp
SelectColumn
SelectEntireTable
SelectFrameByName
SelectRow
SelectStyle
SelectWindow
SendFrameToBack
SendMail
SetBackPath
SetDataFile
SetDefOptions
SetDlgCallBack
SetDlgItemText
SetDocPath
SetDocVar
SetFormula
SetFrameDefaults
SetGlobalArray
SetGlobalVar
SetIconPath
SetIconSize
SetIndexFile
SetMacroPath
SetMasterFiles
SetStyle
SetStylePath
SetTOCFile
ShowIconBar
ShowTabRuler
SingleStep
SizeColumnRow
SmallCaps
Spacing
SpecialEffects
SpellCheck
StandardView
StatusBarMsg
strcat$
strchr
strfield$
StyleManagement


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 459. Macro Functions T ΓòÉΓòÉΓòÉ

TableGetRange
TableLayout
TableLines
Tables
TabRulerInsert
TabRulerRemove
Thesaurus
TileWindow
TOCOptions
ToggleCleanScreen
ToggleIconBar
ToggleTabRuler
TopOfFile
Truncate
TYPE
TypeOver


See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 460. Macro Functions U - Z ΓòÉΓòÉΓòÉ

UCASE$
Underline
Undo
UpperCase
UserControl
UserSetup
UseWorkingDir
UsingHelp
ViewPreferences
WordUnderline
WriteProfileString




See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically


ΓòÉΓòÉΓòÉ 461. Ami Pro Macro Functions Grouped by Category ΓòÉΓòÉΓòÉ

Ami Pro Menu Bar Macro Functions
Array Macro Functions
ASCII File Macro Functions
Bookmark Macro Functions
Date and Time Macro Functions
Dialog Box Macro Functions
DOS Macro Functions
Doc Info Macro Functions
Dynamic Data Exchange (DDE) Macro Functions
Edit Macro Functions
File Macro Functions
Frame Macro Functions
Header and Footer Macro Functions
Help Macro Functions
Macro Only Functions
Master Document Macro Functions
Merge Macro Functions
Navigation Macro Functions
OS/2 Macro Functions
Page Layout Macro Functions
Paragraph Style Macro Functions
Path Macro Functions
Power Field Macro Functions
Printing Macro Functions
Ruler Macro Functions
SmartIcons Macro Functions
String Macro Functions
Table Macro Functions
Text Formatting Macro Functions
Tools Macro Functions
User Setup Macro Functions
Variable Macro Functions
View Macro Functions
Window Macro Functions

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 462. Ami Pro Menus Bar Macro Functions ΓòÉΓòÉΓòÉ

These functions create and change the Ami Pro menu bars and add, remove, or
change pulldown menus displayed from these menu bars.

AddCascadeMenu
AddCascadeMenuItem
AddMenu
AddMenuItem
ChangeCascadeAction
ChangeMenuAction
CheckMenuItem
DeleteMenu
DeleteMenuItem
GrayMenuItem
InsertCascadeMenu
InsertCascadeMenuItem
InsertMenu
InsertMenuItem
RenameMenuItem
StatusBarMsg

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category


ΓòÉΓòÉΓòÉ 463. Array Macro Functions ΓòÉΓòÉΓòÉ

These functions allow you to position insert, delete, and sort arrays.

AllocGlobalVar
AmiProIndirect
AppGetAppCount
AppGetAppNames
ArrayDelete
ArrayInsert
ArrayInsertByKey
ArraySearch
ArraySize
ArraySort
GetBookMarkCount
GetBookMarkNames
GetGlobalArray$
GetMasterFiles
GetMasterFilesCount
GetOpenFileCount
GetOpenFileNames
GetPowerFields
GetStyleNames
SetGlobalArray

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Overview of the Ami Pro Macro Language


ΓòÉΓòÉΓòÉ 464. ASCII File Macro Functions ΓòÉΓòÉΓòÉ

These functions allow a macro to read and write ASCII text files. Reading and
writing binary files is not supported. File operations on binary files may
behave unpredictably.

These are low-level functions that require you to open and close files properly
when you use them. OS/2 may have difficulty if a macro does not close its
files.

BinToBrackets
BracketsToBin
fclose
fgets$
fopen
fputs
fread
fseek
ftell
fwrite

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category


ΓòÉΓòÉΓòÉ 465. Bookmark Macro Functions ΓòÉΓòÉΓòÉ

GetBookMarkCount
GetBookMarkNames
GetBookMarkPage
GetFmtPageStr$
MarkBookMark
SelectFrameByName

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 466. Date and Time Macro Functions ΓòÉΓòÉΓòÉ

DateDiff
FormatDate$
FormatTime$
GetTime
InsertDate
InsertVariable
New

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 467. Dialog Box Macro Functions ΓòÉΓòÉΓòÉ

You can store dialog boxes within a macro. You can define a function or
functions to run while the box is displayed. These functions can change the
components of the box while the box is displayed. Bitmaps can be included as
part of a dialog box. These bitmaps can be static or defined as a button. You
can reproduce the functions of the OS/2 interface using the Ami Pro dialog box.

AnswerMsgBox
Decide
DialogBox
DlgClearControl
DlgClose
DlgEnableControl
DlgGetListBoxCount
DlgGetListBoxLines
DlgHideControl
DlgKeyInterrupt
DlgLimitText
DlgSetCaption
FillEdit
FillList
GetDialogField$
GetDlgItem
GetDlgItemText
Message
Messages$
Query$
SetDlgCallBack
SetDlgItemText
UserControl

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Using the Lotus Dialog Editor


ΓòÉΓòÉΓòÉ 468. DOS Macro Functions ΓòÉΓòÉΓòÉ

These functions allow you to perform the most common DOS commands.

Beep
DOSchdir
DOSCopyFile
DOSDelFile
DOSGetEnv$
DOSGetFileAttr
DOSmkdir
DOSRename
DOSrmdir
DOSSetFileAttr

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category


ΓòÉΓòÉΓòÉ 469. Doc Info Macro Functions ΓòÉΓòÉΓòÉ

DocInfo
DocInfoFields
GetDocInfo$
GetDocInfoKeywords$
GetDocVar
InsertDocInfo
InsertDocInfoField
RenameDocInfoField
SetDocVar

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 470. Dynamic Data Exchange (DDE) Macro Functions ΓòÉΓòÉΓòÉ

DDEAdvise
DDEExecute
DDEInitiate
DDELinks
DDEPoke
DDEReceive$
DDETerminate
DDEUnadvise

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category




ΓòÉΓòÉΓòÉ 471. Edit Macro Functions ΓòÉΓòÉΓòÉ

Copy
Cut
FindReplace
Glossary
GlossaryAdd
GlossaryClose
GlossaryLookup
GlossaryOpen
GlossSet
GoToAgain
GoToCmd
InsertBullet
InsertNote
NoHyphenation
Notes
Paste
Replace
Revert
Type
TypeOver
Undo

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category






ΓòÉΓòÉΓòÉ 472. File Macro Functions ΓòÉΓòÉΓòÉ

ASCIIOptions
AssignMacroToFile
DOSCopyFile
DOSDelFile
DOSGetFileAttr
DOSRename
DOSSetFileAttr
FileChanged
FileClose
FileManagement
FileOpen
FindFirst$
FindNext$
ImportExport
New
OpenPreviousFile
ReadMail
Revert
Save
SaveAs
SendMail

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 473. Frame Macro Functions ΓòÉΓòÉΓòÉ

These functions give you control over the frame position, frame type, lines
around, background color, and drop shadow color. With the frame control
functions, you can change the frame's position, appearance, and type.

AddFrame
AddFrameDlg
BringFrameToFront
FrameLayout
FrameModBorders
FrameModColumns
FrameModFinish
FrameModInit
FrameModLines
FrameModType
GetCurFrameBorders
GetCurFrameLines
GetCurFrameType
ImportPicture
IsFrameSelected
ManualFrame
SelectFrameByName
SendFrameToBack
SetFrameDefaults

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category




ΓòÉΓòÉΓòÉ 474. Header and Footer Macro Functions ΓòÉΓòÉΓòÉ

HeaderFooter
ModLayoutLeftFooter
ModLayoutLeftHeader
ModLayoutRightFooter
ModLayoutRightHeader

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 475. Help Macro Functions ΓòÉΓòÉΓòÉ

About
Help
HowDoIHelp
MacroHelp
UsingHelp

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 476. Macro Only Functions ΓòÉΓòÉΓòÉ

AssignMacroToFile
ChangeShortcutKey
GetRunningMacroFile$
GetRunningMacroName
HourGlass
IgnoreKeyboard
KeyInterrupt
MacroEdit
MacroHelp
MacroOptions
MacroPlay
MouseInterrupt
OnKey
Pause
RunLater
SingleStep

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Overview of the Ami Pro Macro Language





ΓòÉΓòÉΓòÉ 477. Master Document Macro Funtions ΓòÉΓòÉΓòÉ

Generate
GetMasterFiles
GetMasterFilesCount
MarkIndexWord
MarkTOCEntry
MasterDoc
PhysicalToLogical
SetIndexFile
SetMasterFiles
SetTOCFile
TOCOptions

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 478. Merge Macro Functions ΓòÉΓòÉΓòÉ

CreateDataFile
CreateDescriptionFile
InsertMerge
InsertMergeField
Merge
MergeAction
MergeMacro
MergeToFile
OpenDataFile
OpenMergeFile
RecClose
RecFieldCount
RecFieldName
RecGetField
RecNextRec
RecOpen
SetDataFile

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category




ΓòÉΓòÉΓòÉ 479. Navigation Macro Functions ΓòÉΓòÉΓòÉ

AtEOF
CharLeft
CharRight
ElevatorLeftRight
ElevatorUpDown
EndOfFile
GoToAgain
GoToCmd
GoToPowerField
LeftEdge
LineDown
LineUp
PageDown
PageUp
RightEdge
ScreenDown
ScreenLeft
ScreenRight
ScreenUp
TopOfFile
Type

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 480. OS/2 Macro Functions ΓòÉΓòÉΓòÉ

These functions allow Ami Pro to use OS/2 Dynamic Data Exchange (DDE) to
interact with other OS/2 programs and access Dynamic Link Libraries (DLL) and
the routines built into these DLL libraries. A function is also included to
execute another application.

ActivateApp
AppClose
AppGetAppCount
AppGetAppNames
AppGetWindowPos
AppHide
AppIsRunning
AppMaximize
AppMinimize
AppMove
AppRestore
AppSendMessage
AppSize
DDEAdvise
DDEExecute
DDEInitiate
DDELinks
DDEPoke
DDEReceive$
DDETerminate
DDEUnAdvise
DLLCall
DLLFreeLib
DLLLoadLib
Exec
GetDlgItem
GetProfileString$
WriteProfileString

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 481. Page Layout  Macro Functions ΓòÉΓòÉΓòÉ

These functions give you control over creating or modifying the page layout.

GetLayoutLeftLines
GetLayoutPageSize
GetLayoutParameters
GetLayoutType
InsertLayout
ModifyLayout
ModLayoutFinish
ModLayoutInit
ModLayoutLeftFooter
ModLayoutLeftHeader
ModLayoutLeftLines
ModLayoutLeftPage
ModLayoutPageSize
ModLayoutRightFooter
ModLayoutRightHeader
ModLayoutRightLines
ModLayoutRightPage
PageBreak
PageNumber
RemoveLayout
RevertLayout
GetPageNo
LineNumber

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category


ΓòÉΓòÉΓòÉ 482. Paragraph Style Macro Functions ΓòÉΓòÉΓòÉ

These functions give you control over paragraph styles.

CreateStyle
DefineStyle
FormatSeq$
GetSpecialEffects$
GetStyleCount
GetStyleName$
GetStyleNames
ModifyAlignment
ModifyBreaks
ModifyEffects
ModifyFont
ModifyLines
ModifyReflow
ModifySelect
ModifySpacing
ModifyStyle
ModifyTable
OutlineLevels
OutlineStyle
SaveAsNewStyle
SelectStyle
SetStyle
StyleManagement

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category





ΓòÉΓòÉΓòÉ 483. Path Macro Functions ΓòÉΓòÉΓòÉ

GetAmiDirectory$
GetBackPath$
GetCurrentDir$
GetDocPath$
GetHomeDirectory$
GetMacPath$
GetOpenFileName$
GetOpenFileNames$
GetStylePath$
SetBackPath$
SetDocPath$
SetIconPath$
SetMacroPath$
SetStylePath$
UseWorkingDir$

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category


ΓòÉΓòÉΓòÉ 484. Power Field Macro Functions ΓòÉΓòÉΓòÉ

EvalField
FieldAdd
FieldAuto
FieldCommand
FieldEvaluate
FieldLock
FieldNext/FieldPrev
FieldRemove
FieldToggleDisplay
FieldUpdate
FieldUpdateAll
GetPowerFieldCount
GetPowerFieldPage
GetPowerFields
GoToPowerField

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 485. Printing Macro Functions ΓòÉΓòÉΓòÉ

FilePrint
Merge
MergeAction
MergeMacro
PrintEnvelope
PrintOptions
PrintSetup

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 486. Ruler Macro Functions ΓòÉΓòÉΓòÉ

HideTabRuler
ShowTabRuler
TabRulerInsert
TabRulerRemove
ToggleTabRuler

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category


ΓòÉΓòÉΓòÉ 487. SmartIcons Macro Functions ΓòÉΓòÉΓòÉ

ChangeIcons
GetIconPalette
HideIconBar
IconBottom
IconCustomize
IconFloating
IconLeft
IconRight
IconTop
SetIconSize
ShowIconBar
ToggleIconBar

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 488. String Macro Functions ΓòÉΓòÉΓòÉ

These functions manipulate strings of text. Many of these functions are similar
to, and have the same syntax as, BASIC language string functions.

ASC
BinToBrackets
BracketsToBin
CHR$
CurChar$
CurShade$
CurWord$
DateDiff
DOSGetEnv$
fgets$
FormatDate$
FormatNum$
FormatSeq$
FormatTime$
GetAmiDirectory$
GetBackPath$
GetCurrentDir$
GetDialogField$
GetDocInfo$
GetDocInfoKeywords$
GetDocPath$
GetFmtPageStr$
GetGlobalArray$
GetGlobalVar$
GetMacPath$
GetMarkText$
GetOpenFileName$
GetProfileString$
GetRunningMacroFile$
GetRunningMacroName$
GetSpecialEffects$
GetStylePath$
GetTextBeforeCursor$
Instr
IsNumeric
LCASE$
Left$
LEN
MID$
Mod
Right$
Round
strcat$
strchr
strfield$
Truncate
TYPE
UCASE$
WriteProfileString

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Overview of the Ami Pro Macro Language


ΓòÉΓòÉΓòÉ 489. Table Macro Functions ΓòÉΓòÉΓòÉ

ConnectCells
DeleteColumnRow
DeleteEntireTable
EditFormula
InsertColumnRow
LeaderDots
LeaderHyphs
LeaderLines
LeaderNone
ProtectCells
QuickAddCol
QuickAddRow
SelectColumn
SelectEntireTable
SelectRow
SetFormula
SizeColumnRow
TableGetRange
TableLayout
TableLines
Tables
See also:
    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 490. Text Formatting Macro Functions ΓòÉΓòÉΓòÉ

ApplyFormat
Bold
Center
FastFormat
FontChange
FontFaceChange
FontPointSizeChange
FontRevert
GetCurFontInfo
Indent
IndentAll
IndentFirst
IndentRest
Italic
Justify
LeftAlign
LowerCase
NoHyphenation
NormalText
RightAlign
SmallCaps
Spacing
SpecialEffects
Underline
UpperCase
WordUnderline
See also:
    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 491. Tools Macro Functions ΓòÉΓòÉΓòÉ

ChangeLanguage
Equations
Footnotes
ImageProcessing
ReviewRevisions
RevisionInsertion
RevisionMarking
RevisionMarkOpts
SpellCheck
Thesaurus
See also:
    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 492. User Setup Macro Functions ΓòÉΓòÉΓòÉ

LoadOptions
SetBackPath
SetDefOptions
SetDocPath
SetIconPath
SetMacroPath
SetStylePath
UserSetup
UseWorkingDir
See also:
    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category



ΓòÉΓòÉΓòÉ 493. Variable Macro Functions ΓòÉΓòÉΓòÉ

Most variables are local and private to the macro in which they are declared.
They are deleted when the macro completes. Ami Pro provides variables that are
saved when a macro completes.

AllocGlobalVar
Assign
DOSGetEnv$
FreeGlobalVar
GetDocVar
GetGlobalVar$
GetGlobalVarCount
GetGlobalVarNames
SetDocVar
SetGlobalVar

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Overview of the Ami Pro Macro Language
    Using Variables


ΓòÉΓòÉΓòÉ 494. View Macro Functions ΓòÉΓòÉΓòÉ

CleanScreenOptions
CustomView
DraftMode
EnlargedView
FacingView
GetMode
GetViewLevel
GetViewPrefLevel
GetViewPrefOpts
LayoutMode
OutlineMode
StandardView
ToggleCleanScreen
ViewPreferences

See also:
    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Using Variables


ΓòÉΓòÉΓòÉ 495. Window_Macro_Functions ΓòÉΓòÉΓòÉ

CascadeWindow
FieldToggleDisplay
FullPageView
GetOpenFileCount
Maximize
Minimize
NewWindow
NextWindow
Restore
SelectWindow
TileWindow

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped by Category
    Using Variables


ΓòÉΓòÉΓòÉ 496. Debugging Macros ΓòÉΓòÉΓòÉ

This section of the documentation describes error messages that can appear when
compiling or running macros. It also discusses some of the techniques you can
use to determine the cause of the errors, and how you can test your macros to
make sure they do what you want them to.


Error Messages When Macros Are Compiled
When an error occurs during macro compilation, the insertion point stops at the
location of the error, and a message displays. Error messages that only contain
an error number are out of memory error messages. The macro is not saved. You
can determine the cause of the error, make the change, and recompile the macro.
Compilation stops at the first error found, so you may need to compile the
macro several times in order to find all the errors.

Error Messages While Macros Are Running
Runtime error handling is dependent on whether the SingleStep function has been
used in the compiled macro. If a SingleStep function has been used, a runtime
error displays a message box with the error message as the title of the message
box and the offending line inside the dialog box. When the user acknowledges
the error, the macro is canceled.

If no SingleStep statement has been used, the error message displays on the
screen without the line information. When the user acknowledges the error, the
macro is canceled.

A run-time error, whether a macro error, or an Ami Pro or OS/2 error, stops
macro execution unless an ONERROR statement has been included in the macro. If
an ONERROR statement has been included, control transfers to the location
specified by that statement.

Determining the Cause of Runtime Errors
Runtime errors can be difficult to trace and debug. If other people will be
using your macros, you should test them and make sure they work correctly
before distributing them. Ami Pro provides several macro functions you can use
to determine the cause of run-time errors and trace the progress of your macro.
These functions are:
    IgnoreKeyboard
    SingleStep
    Message
    Messages
In addition, you can use Debug to identify run-time errors and to display
variables and modify their values. To debug a macro file, open the macro file,
choose Tools Macros, and chooseDebug. You can play the entire macro or you can
check each step in the macro.

See also:

    Ami Pro Macro Language Contents
    Macro Error Messages
    SingleStep
    Using Debug
    Using the Message Function
    Using the Messages Function
    Using the ONERROR Statement
    Using the SingleStep and IgnoreKeyboard Functions




ΓòÉΓòÉΓòÉ 497. Using Debug ΓòÉΓòÉΓòÉ

You can use Debug to identify run-time errors in a macro. These errors occur
when you play the macro, even though the macro saved properly.


You can also display variables and modify their values.

To debug a macro file
 1.  Choose Tools Macros.
 2.  Choose Edit.
 3.  Select the macro file you want to debug and choose OK.
    Ami Pro displays the macro file.
 4.  Choose Tools Macros.
 5.  Choose Debug.
    The Debug dialog box displays and remains on the screen so you can continue
    to check the macro.

To play the macro
Choose Run/Continue.
If a run-time error is encountered, Ami Pro displays an error message and
pauses the macro.
Choose the desired command button to resume checking the macro.

To check each step in the macro
Choose Single Step to play the macro and pause at every step.
Choose Step Through to play the macro but not pause at any steps that are part
of another function.
Choose the desired command button to resume checking the macro.

To stop playing the macro
Choose Abort or Interrupt.
These buttons replace the Select Macro button while Ami Pro plays the macro.
The macro file remains in the window so you can continue debugging it.
To debug another macro
Make the desired macro file the active window and choose Select Macro.
Ami Pro changes the macro file name in the Debug dialog box.
You can now specify whether you want to play the macro or check each step in
the macro.

To display variables and modify their values
If the Debug dialog box is open, you can display a list of macro variables and
their values. You can modify the values and then continue the macro with the
new values.
 1.  Choose Variables in the Debug dialog box.
    The Variables dialog box displays and remains on the screen so you can
    continue to display variables and modify their values.
 2.  Select the desired variable.
 3.  Type the New Value you want to use.
 4.  Choose Update if you want to assign a new value to the variable.
 5.  Choose the desired command button in the Debug dialog box to play the
macro.
 6.  Choose Close to close the Variables dialog box when you no longer need to
display the variables.

See also:

    Ami Pro Macro Language Contents
    Debugging Macros
    Macro Error Messages
    Using the Message Function
    Using the Messages Function
    Using the SingleStep and IgnoreKeyboard Functions




ΓòÉΓòÉΓòÉ 498. Using the SingleStep and IgnoreKeyboard Functions ΓòÉΓòÉΓòÉ

The SingleStep function is auseful because it allows you to trace the progress
of your macro. When you use control statements in your macro, it may do
something you don't expect if the value tested by the control statement is
something you hadn't planned on. In single step mode, each statement is
displayed as it is executed so that you can tell what your macro is doing. You
can verify that the tests placed in your control statements do what you
planned.


If you use the SingleStep function and an error occurs, you will see
information about the line that caused the problem. If the SingleStep function
is not used, all that is shown is the error message with no indication of where
the problem is.

Any variables defined before the SingleStep function will not be available for
viewing or changing. Also, any variable not yet defined when the macro is
interrupted will not be available. When you use the StepThrough feature of
SingleStep and the next statement is a Call function, all statements in the
macro and any macros called will be executed without interruption. Once the
called macro ends, the macro will again be interrupted. If the next statement
is not a macro call, then StepThrough acts just like SingleStep. If a
SingleStep(0) is encountered while stepping through the macro, it will not have
an effect on the macro. If a SingleStep(1) is encountered, the macro will be
interrupted.

Other tools that can help you debug your macros are the IgnoreKeyboard,
Message, and Messages functions. The IgnoreKeyboard function determines if any
key will interrupt a macro or if only the Escape key will interrupt the macro.
The Message function displays a message on the screen and then waits for the
user to acknowledge it. The Messages function determines if messages issued by
Ami Pro will be shown to the user or if they will be accepted and the default
action taken.

If the SingleStep function has not been used in your macro, the macro user can
press a key to interrupt macro play. When a key is pressed, a message appears
asking the user if macro play should be continued or canceled. The
IgnoreKeyboard function determines if pressing any key pauses the macro (the
default) or if pressing only the Escape key pauses the macro.

If you use the SingleStep function, pausing the macro by pressing a key will
cause the macro to enter single step mode. You will be able to continue macro
play normally, continue in single step mode, or cancel macro play completely.
This allows you to see what is happening in your macro if it appears to be in
an infinite loop.

Example
The following example illustrates using the SingleStep Function to determine
the cause of an infinite loop:
FUNCTION debug
SingleStep (Off)  ' allow debugging
var1 = 1  ' initialize var1
var2 = 2  ' initialize var2
while (var1 < 10)  ' set loop to continue until var1 = 10
   IF (var2 > 0)
      var1 = var1 - 1  ' decrement var1 if var2 > 0
   ENDIF
   var1 = var1 + 1 ' increment var2
WEND
END FUNCTION

In this example, a while loop is used to execute program steps while var1 is
less than 10. The last statement in the WHILE loop increments var1, so the
macro should execute the loop 10 times and then end. The IF statement in line 6
decrements var1 if var2 is greater than 0. Since var2 is equal to 2, this means
that var1 will always be decremented. This means that var1 will never increase
as it passes through the loop, since it will be decremented in line 7 and then
incremented in line 9. This means the loop will never end.

If this macro were run, Ami Pro would appear to freeze with the clock icon
displayed. By using SingleStep mode, pressing a key while the macro was running
would allow the programmer to view the progress of the loop and determine the
problem.


See also:

    Ami Pro Macro Language Contents
    IgnoreKeyboard
    Macro Error Messages
    Message
    Messages
    SingleStep
    Using the Message Function
    Using the Messages Function



ΓòÉΓòÉΓòÉ 499. Using the Message Function ΓòÉΓòÉΓòÉ

The Message function can be used to display the value of a variable as your
macro executes. This can assist you in determining if variable values stay
within the range you expect.


Example
Consider the following example:
FUNCTION testswitch
choice = Query$ ("Type a number between 1 and 3")
SWITCH choice
   CASE ("1")
      ' statements for case 1
   CASE ("2")
      ' statements for case 2
   CASE ("3")
      ' statements for case 3
   DEFAULT
      message ("Got back {choice} for user's choice")
ENDSWITCH
END FUNCTION

This example uses a SWITCH statement to execute macro statements based on a
value typed in by the user. The Message statement in line 11 displays a message
indicating the value of the switch variable if it wasn't one of the values
expected. While this example is simple, placing messages in your macros can be
helpful when debugging. This can be particularly true if the value being tested
in a SWITCH statement is determined by the macro or is the result of a
function.


See also:

    Ami Pro Macro Language Contents
    Message
    Using the Messages Function
    Using the SingleStep and IgnoreKeyboard Functions




ΓòÉΓòÉΓòÉ 500. Using the Messages Function ΓòÉΓòÉΓòÉ

The Messages function determines the action taken by a macro in response to
unexpected Ami Pro messages. For instance, when a new file is opened, Ami Pro
asks if the current file's changes should be saved. By using the Messages
function, the macro can automatically take the default action for these
messages without interrupting the macro user.


In the early stages of developing a complicated macro, you may want to leave
message display on. This helps you determine that the functions in the macro do
what you want them to. Once you are sure that the macro is working correctly,
you can turn messages off.


See also:

    Ami Pro Macro Language Contents
    Messages
    Using the SingleStep and IgnoreKeyboard Functions
    Using the Message Function



ΓòÉΓòÉΓòÉ 501. Ami Pro Macro Functions Grouped By Menu ΓòÉΓòÉΓòÉ

Edit Menu
File Menu
Frame Menu
Help Menu
Page Menu
Style Menu
System Menu
Table Menu
Text Menu
Tools Menu
View Menu
Window Menu



See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped Alphabetically
    Ami Pro Macro Functions Grouped by Category


ΓòÉΓòÉΓòÉ 502. Edit Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Bookmarks                                       MarkBookMark
Copy                                            Copy
Cut                                             Cut
Find & Replace                                  FindReplace
                                                (Displays the dialog box)
Find & Replace                                  Replace
                                                (Automatically find & replace)
Go To                                           GoToCmd
Insert Bullet                                   InsertBullet
Insert Date Time                                InsertDate
                                                (Inserts the date, but does not
 display the dialog box)
Insert Date Time                                InsertVariable
                                                (Displays the dialog box)
Insert Doc Info Field                           InsertDocInfo
                                                (Displays the dialog box)
Insert Doc Info Field                           InsertDocInfoField
                                                (Inserts a doc info field, but
 does not display the dialog box)
Insert Glossary Record                          Glossary
Insert Glossary Record Data File                GlossSet
Insert Merge Field                              FieldAdd
                                                (Inserts a merge field, but
 does not display the dialog box)
Insert Merge Field                              InsertMerge
                                                (Displays the dialog box)
Insert Note                                     InsertNote
Link Options                                    DDELinks
Mark Text Glossary                              GlossaryAdd
Mark Text Index Entry                           MarkIndexWord
Mark Text No Hyphenation                        NoHyphenation
Mark Text TOC Entry                             MarkTOCEntry
Mark Text Revision Insertion                    RevisionInsertion
Paste                                           Paste
Power Fields Insert                             FieldAdd
                                                (Inserts a power field, but
 does not display the dialog box)
Power Fields Insert                             FieldCommand
                                                (Displays the dialog box)
Power Fields Next Field                         FieldNext/FieldPrev
Power Fields Prev Field                         FieldNext/FieldPrev
Power Fields Update                             FieldEvaluate
Power Fields Update                             FieldUpdate
Power Fields Update All                         FieldUpdateAll
Undo                                            Undo

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu



ΓòÉΓòÉΓòÉ 503. File Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Close                                           FileClose
Doc Info                                        DocInfo
File Management                                 FileManagement
Import Picture                                  ImportPicture
Master Document                                 MasterDoc
Merge                                           Merge
New                                             New
Open                                            FileOpen
Open a Previous File                            OpenPreviousFile
Print Envelope                                  PrintEnvelope
Print                                           FilePrint
Printer Setup                                   PrintSetup
Revert to Saved                                 Revert
Save                                            Save
Save As                                         SaveAs
Send Mail                                       SendMail

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 504. Frame Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Bring to Front                                  BringFrameToFront
Create Frame                                    AddFrame
                                                 (Creates a frame but does not
 display the dialog box)
Create Frame                                    AddFrameDlg
                                                (Displays the dialog box)
Create Frame Manually                           ManualFrame
Modify Frame Layout                             FrameLayout
Send to Back                                    SendFrameToBack

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 505. Help Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
About Ami Pro                                   About
Contents                                        Help
How Do I?                                       HowDoIHelp
Macro Doc                                       MacroHelp
Using Help                                      UsingHelp

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 506. Page Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Breaks                                          PageBreak
Header Footer                                   HeaderFooter
Insert Page Layout Insert                       InsertLayout
Insert Page Layout Remove                       RemoveLayout
Insert Page Layout Revert                       RevertLayout
Line Numbering                                  LineNumber
Modify Page Layout                              ModifyLayout
Page Numbering                                  PageNumber
Ruler Remove                                    TabRulerRemove
Ruler Insert                                    TabRulerInsert

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 507. Style Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Create Style                                    CreateStyle
Define Style                                    DefineStyle
Modify Style                                    ModifyStyle
Outline Styles                                  OutlineStyle
Save as a Style Sheet                           SaveAsNewStyle
Select a Style                                  SelectStyle
Style Management                                StyleManagement
                                                (Displays the dialog box)

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 508. System Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Close                                           AppClose
Maximize                                        Maximize
Minimize                                        Minimize
Move                                            AppMove
Restore                                         Restore
Size                                            AppSize
Window List                                     ActivateApp

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu




ΓòÉΓòÉΓòÉ 509. Table Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Column Row Size                                 SizeColumnRow
Connect Cells                                   ConnectCells
Delete Column Row                               DeleteColumnRow
Delete Entire Table                             DeleteEntireTable
Edit Formula                                    EditFormula
                                                (Displays the dialog box)
Edit Formula                                    SetFormula
                                                (Inserts the formula but does
 not display the dialog box)
Insert Column Row                               InsertColumnRow
Leaders None                                    LeaderNone
Leaders---                                      LeaderHyphs
Leaders...                                      LeaderDots
Leaders___                                      LeaderLines
Lines & Color                                   TableLines
Modify Table Layout                             TableLayout
Protect Cells                                   ProtectCells
Quick Add Column                                QuickAddCol
Quick Add Row                                   QuickAddRow
Select Row                                      SelectRow
Select Column                                   SelectColumn
Select Entire Table                             SelectEntireTable

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 510. Text Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Alignment Center                                Center
Alignment Left                                  LeftAlign
Alignment Right                                 RightAlign
Alignment Justify                               Justify
Bold                                            Bold
Caps Upper Case                                 UpperCase
Caps Lower  case                                LowerCase
Caps Small Caps                                 SmallCaps
Fast Format                                     FastFormat
Font                                            FontChange
Indention                                       Indent
Italic                                          Italic
Normal                                          NormalText
Spacing                                         Spacing
Special Effects                                 SpecialEffects
Underline                                       Underline
Word Underline                                  WordUnderline

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 511. Tools Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Equations                                       Equations
Footnotes                                       Footnotes
Generate Index                                  Generate
Generate TOC                                    Generate
Image Processing                                ImageProcessing
Macros Edit                                     MacroEdit
Macros Playback                                 MacroPlay
Revision Marking                                RevisionMarking
SmartIcons                                      IconCustomize
Spell Check                                     SpellCheck
Tables                                          Tables
Thesaurus                                       Thesaurus
User Setup                                      UserSetup

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu
    Table Menu


ΓòÉΓòÉΓòÉ 512. View Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Custom                                          CustomView
Draft Mode                                      DraftMode
Enlarged                                        EnlargedView
Facing Pages                                    FacingView
Full Page                                       FullPageView
Hide Clean Screen                               ToggleCleanScreen
Hide Power Fields                               FieldToggleDisplay
Hide Ruler                                      HideTabRuler
                                                ToggleTabRuler
Hide SmartIcons                                 HideIconBar
                                                ToggleIconBar
Layout Mode                                     LayoutMode
Outline Mode                                    OutlineMode
Show Clean Screen                               ToggleCleanScreen
Show Power Fields                               FieldToggleDisplay
Show Ruler                                      ShowTabRuler
                                                ToggleTabRuler
Show SmartIcons                                 ShowIconBar
                                                ToggleIconBar
Standard                                        StandardView
View Preferences                                ViewPreferences

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 513. Window Menu ΓòÉΓòÉΓòÉ

Menu Item                                       Equivalent Macro Function
Cascade                                         CascadeWindow
New Window                                      NewWindow
Tile                                            TileWindow

See also:

    Ami Pro Macro Language Contents
    Ami Pro Macro Functions Grouped By Menu


ΓòÉΓòÉΓòÉ 514. Macro Error Messages ΓòÉΓòÉΓòÉ

This section of the macro documentation lists each of the error messages that
could appear during macro compilation and execution, along with suggestions for
determining the cause of the problem. It does not cover the regular Ami Pro or
OS/2 error messages.


Ami Pro replaces the variables %s, %c, and %1d with the actual string, number,
filename, etc. causing the problem.

    Do you want to cancel the macro?
    Internal Runtime Error %1d
    Macro Error Messages 1 - 40
    Macro Error Messages 41 - 80
    Macro Error Messages 81 - 120
    Macro Error Messages 121 - End


See also:

    Ami Pro Macro Language Contents
    Debugging Macros



ΓòÉΓòÉΓòÉ 515. Macro Error Messages 1 - 40 ΓòÉΓòÉΓòÉ

    Error 1 : Incorrect format used for this function
    Error 2 : Symbol %s not recognized
    Error 3 : Memory not available
    Error 4 : %s is already defined as an array
    Error 5 : Array name must be followed by )
    Error 6 : Incorrect expression as array argument
    Error 7 : Incorrect expression, expecting )
    Error 8 : Incorrect parameter count
    Error 9 : Misplaced keyword %s
    Error 10 : Token file is unreadable
    Error 11 : FUNCTION argument (%s) is already defined
    Error 12 : FUNCTION statement has incorrect format
    Error 13 : DECLARE statement has incorrect format
    Error 14 : DECLARE or CALL statement has incorrect format
    Error 15 : Variable name %s is not appropriate here
    Error 16 : Symbol %s is not recognized
    Error 17 : END FUNCTION statement was not found.
    Error 18 : Expecting ( instead of %s here
    Error 19 : Expecting ENDIF instead of %s here
    Error 20 : Expecting %s instead of ELSEIF here
    Error 21 : Expecting %s instead of ELSE here
    Error 22 : Expecting %s instead of ENDIF here
    Error 23 : Expecting %s instead of NEXT here
    Error 24 : WHILE statement has incorrect format
    Error 25 : CASE statement must follow SWITCH statement
    Error 26 : Variable name must follow SWITCH statement
    Error 27 : Expecting %s instead of CASE here
    Error 28 : Expecting %s instead of DEFAULT here
    Error 29 : Expecting %s instead of ENDSWITCH here
    Error 30 : BREAK statement is inappropriate here
    Error 31 : Expecting %s instead of FUNCTION here
    Error 32 : Expecting %s instead of END FUNCTION here
    Error 33 : Incorrect format used for CALL statement
    Error 34 : Label %s is not defined
    Error 35 : %s is already defined
    Error 36 : Incorrect number of parameters: function %s
    Error 37 : Incorrect format used for DIM statement
    Error 38 : Incorrect format used for DEFSTR statement
    Error 39 : Incorrect array expression
    Error 40 : Assignment expected after FOR statement


See also:

    Ami Pro Macro Language Contents
    Macro Error Messages Contents
    Macro Error Messages 41 - 80
    Macro Error Messages 81 - 120
    Macro Error Messages 121 - End




ΓòÉΓòÉΓòÉ 516. Macro Error Messages 41 - 80 ΓòÉΓòÉΓòÉ

    Error 41 : TO expected in FOR statement
    Error 42 : Improper label used in GOTO statement
    Error 43 : Incorrect syntax used in DECLARE statement
    Error 44 : No macros found in file
    Error 45 : Incorrect character %c used here
    Error 46 : Macro line can't end like this
    Error 47 : Token file has become damaged
    Error 48 : %s is an improper keyname
    Error 49 : Too many characters in this string
    Error 50 : Called macro must have a filename or be in the current macro
    file
    Error 51 : Macro %s not found
    Error 52 : Insufficient memory to execute this macro
    Error 53 : Insufficient memory to execute this macro
    Error 54 : DDEReceive could not be executed
    Error 55 : DDEReceive did not get data back from the other program
    Error 56 : Incorrect parameters used for DDEReceive function
    Error 58 : Incorrect parameters used for DDEExecute function
    Error 59 : Incorrect Parameters used %s Line %1d
    Error 60 : Can't read macro file
    Error 61 : Internal error, start address %s
    Error 62 : Internal error, opcode %s
    Error 63 : Internal error, function %1d
    Error 64 : Internal error, parm count %s Line %1d
    Error 65 : Internal error, no function number %s Line %1d
    Error 66 : Internal error, bad logop
    Error 67 : Internal error, logop stack
    Error 68 : Internal error, relop stack
    Error 69 : Internal error, mathops stack
    Error 70 : Internal error, bad mathop
    Error 71 : Attempt to add non-numeric values %s Line %1d
    Error 72 : Attempt to divide by zero, %s Line %1d
    Error 73 : Attempted math function on non-numeric values, %s Line %1d
    Error 74 : Internal error, bad mulop
    Error 75 : Internal error, POPVAR stack
    Error 76 : Internal error, JMPF stack
    Error 77 : Internal error, JMPF stack
    Error 78 : Internal error, POPRLT stack
    Error 79 : Internal error, call address %s
    Error 80 : Array index out of range


See also:

    Ami Pro Macro Language Contents
    Macro Error Messages Contents
    Macro Error Messages 1 - 40
    Macro Error Messages 81 - 120
    Macro Error Messages 121 - End




ΓòÉΓòÉΓòÉ 517. Macro Error Messages 81 - 120 ΓòÉΓòÉΓòÉ

    Error 81 : Macro called Ami Pro Function that has been grayed
    Error 82 : ONERROR or ONCANCEL can't be in a called macro
    Error 83 : Macro referenced in CALL statement can't be found
    Error 84 : Insufficient memory for AddMenu functions
    Error 86 : Unable to complete CreateMenu function
    Error 87 : Maximum menu count reached in AddMenu function
    Error 89 : Unable to complete menu function, Lock failure
    Error 90 : Unable to create new menu
    Error 91 : Maximum count reached in AddMenuItem
    Error 92 : Insufficient memory for menu functions.
    Error 93 : Internal Error, shrinking menus
    Error 94 : Internal Error, symbol number
    Error 95 : Internal Error, symbol number
    Error 96 : Internal Error, grow strings
    Error 97 : Internal Error, strings
    Error 98 : Internal Error, grow strings
    Error 99 : Internal Error, lock strings
    Error 100 : Internal Error, realloc array
    Error 101 : Internal Error, string frame
    Error 102 : Internal Error, no stack
    Error 103 : Index out of bounds in global array
    Error 104 : Insufficient memory to run this macro
    Error 105 : Unknown global variable used
    Error 106 : Incorrect parameter used for this function
    Error 107 : Insufficient memory to run this macro
    Error 108 : %s is not a macro file
    Error 109 : Incorrect combination of keyword(s)
    Error 110 : Incorrect offset for start of string
    Error 111 : THEN statement is inappropriate here
    Error 112 : Record function(s) couldn't be translated
    Error 113 : Unknown token %s, is not a valid parameter.
    Error 114 : Function %s has not been declared.
    Error 115 : Failure to lock global memory.
    Error 116 : Corrupt variable.
    Error 117 : Invalid variable type (%1d).
    Error 118 : Mismatch on assignment (%1d).
    Error 119 : Memory allocation failure (%1d).
    Error 120 : Wrong data type for operation (%1d).


See also:

    Ami Pro Macro Language Contents
    Macro Error Messages Contents
    Macro Error Messages 1 - 40
    Macro Error Messages 41 - 80
    Macro Error Messages 121 - End


ΓòÉΓòÉΓòÉ 518. Macro Error Messages 120 - End ΓòÉΓòÉΓòÉ

    Error 121 : GlobalLock failure (%1d).
    Error 122 : Variable confusion.
    Error 124 : Field does not end properly.
    Error 125 : Field number out of range.
    Error 126 : Quoted string not properly terminated.
    Error 127 : Call statement must reference a macroname.
    Error 129 : Invalid number for FormatDate.
    Error 130 : Failed to Exec %s.
    Error 131 : Indirect variable required. (Use &variable)
    Error 132 : Array variable required for this function.
    Error 133 : Incorrect number of parameters.
    Error 134 : Only one macro may be paused at a time.
    Error 135 : Invalid DIALOG BOX format.
    Error 136 : Misplaced Keyword DIALOG. DIALOG boxes must be defined outside
    of functions.
    Error 137 : Misplaced Keyword END DIALOG.
    Error 138 : Illegal use of indirection.
    Error 139 : Invalid argument to ALIAS.
    Error 140 : Invalid argument.
    Error 142 : DEFINE (%s) identifier must be undefined.
    Error 143 : DEFINE closing parenthesis expected.
    Error 144 : Invalid syntax for DEFINE.
    Error 145 : Replacement to long for DEFINE.
    Error 146 : Duplicate DEFINE/Variable name (%s).
    Error 147 : Line too long.
    Error 149 : Open parenthesis unexpected.
    Error 150 : Invalid Dll ID.
    Error 151 : Failed to load DLL.
    Error 152 : Failed to open control file.
    Error 153 : Indirect Variable Required
    Error 163 : This function is not supported in this version.


See also:

    Ami Pro Macro Language Contents
    Macro Error Messages Contents
    Macro Error Messages 1 - 40
    Macro Error Messages 41 - 80
    Macro Error Messages 81 - 120


ΓòÉΓòÉΓòÉ 519. Internal Runtime Error %1d ΓòÉΓòÉΓòÉ

This is an internal error. It signifies an unexpected runtime error. It should
not appear. If this message does appear, note the number that is given and then
call Ami Pro customer support for further assistance.


ΓòÉΓòÉΓòÉ 520. Do you want to cancel the macro? ΓòÉΓòÉΓòÉ

This message appears when you did not use SingleStep mode and you pressed a key
during macro execution.

If you choose Yes and the label defined by the ONCANCEL statement was used, the
control transfers to the label. If the label was not used, the macro ends.

If you choose No, macro execution continues.

See also:
    SingleStep
    Using the ONCANCEL Statement



ΓòÉΓòÉΓòÉ 521. Error 1 ΓòÉΓòÉΓòÉ

The format used for this function is not the correct format. Check for missing
parentheses after the function name or at the end of the function. Also check
for improper characters within the parentheses.


ΓòÉΓòÉΓòÉ 522. Error 2 ΓòÉΓòÉΓòÉ

The character at the insertion point is not recognized by the macro compiler.
If it is a variable, check to make sure it has been defined first. If it is a
function, check the spelling of the function name.


ΓòÉΓòÉΓòÉ 523. Error 3 ΓòÉΓòÉΓòÉ

There is not enough memory available to compile the macro. Reduce memory usage
by exiting other applications and then recompile the macro.


ΓòÉΓòÉΓòÉ 524. Error 4 ΓòÉΓòÉΓòÉ

The array name used in this DIM statement is already defined as something else
in this macro. Use another array name.


See also:

    Declaring Formal Variables Using the DIM Statement


ΓòÉΓòÉΓòÉ 525. Error 5 ΓòÉΓòÉΓòÉ

When using an array name, the element number of the array must be surrounded by
parentheses. Check the parentheses and then recompile the macro.


ΓòÉΓòÉΓòÉ 526. Error 6 ΓòÉΓòÉΓòÉ

The element number of this array is not a number or the expression you used
doesn't evaluate to an integer. Correct the expression and then recompile the
macro.


ΓòÉΓòÉΓòÉ 527. Error 7 ΓòÉΓòÉΓòÉ

The number of closing parentheses in this expression does not match the number
of opening parentheses. Count the parentheses, correct errors, and then
recompile the macro.


ΓòÉΓòÉΓòÉ 528. Error 8 ΓòÉΓòÉΓòÉ

You did not provide the correct number of parameters for this function. Check
the requirements of this function, correct errors, and then recompile the
macro.


ΓòÉΓòÉΓòÉ 529. Error 9 ΓòÉΓòÉΓòÉ

The keyword does not belong at this point in the macro. Check the syntax of
what you were trying to do, correct errors, and then recompile the macro.


ΓòÉΓòÉΓòÉ 530. Error 10 ΓòÉΓòÉΓòÉ

This indicates the file MACTOKEN.SAM in the AMIPRO directory is damaged or
missing. You cannot compile the macro until it has been replaced. Call Ami Pro
support for instructions on how to replace this file.


ΓòÉΓòÉΓòÉ 531. Error 11 ΓòÉΓòÉΓòÉ

The arguments you used in the FUNCTION statement have already been defined and
cannot be used at that point. You may have used a function name or a constant
as the macro argument. Check the syntax, correct errors, and then recompile the
macro.


See also:

    Using the FUNCTION Statement


ΓòÉΓòÉΓòÉ 532. Error 12 ΓòÉΓòÉΓòÉ

The format of the FUNCTION statement is incorrect. The syntax of the FUNCTION
statement is FUNCTION macroname([arguments]). Macroname cannot be a name of a
statement or a function. Make sure that you have parentheses following the
macro name and that the name is not a reserved word. Correct errors and then
recompile the macro.


See also:

    Using the FUNCTION Statement




ΓòÉΓòÉΓòÉ 533. Error 13 ΓòÉΓòÉΓòÉ

The format of the DECLARE statement is not correct. The syntax of the DECLARE
statement is DECLARE macroname([arguments]). Make sure that you have
parentheses following the macro name and that you have not used function names
for the arguments. Correct errors and then recompile the macro.


See also:

    Using the DECLARE Statement


ΓòÉΓòÉΓòÉ 534. Error 14 ΓòÉΓòÉΓòÉ

The format of the DECLARE or CALL statement is not correct. The syntax of the
DECLARE statement is DECLARE macroname([arguments]). The format of the CALL
statement is CALL macroname([arguments]). Make sure that you have parentheses
following the macro name and that you have not used function names for the
arguments. Correct errors and then recompile the macro.


See also:

    Using the CALL and CALLI Statements
    Using the DECLARE Statement


ΓòÉΓòÉΓòÉ 535. Error 15 ΓòÉΓòÉΓòÉ

A variable name does not belong at this point in the macro. The macro may be
expecting an array name instead of a variable name. You may have incorrectly
used a variable name instead of a function or statement name. Correct errors
and then recompile the macro.


ΓòÉΓòÉΓòÉ 536. Error 16 ΓòÉΓòÉΓòÉ

The character at the insertion point is not recognized by the macro compiler.
If it is a variable, check to make sure it has been properly defined. If it is
a function, check the spelling of the function name. Correct errors and then
recompile the macro.


ΓòÉΓòÉΓòÉ 537. Error 17 ΓòÉΓòÉΓòÉ

The macro does not have an END FUNCTION statement. Insert an END FUNCTION
statement and then recompile the macro.



See also:

    Using the END Function Statement


ΓòÉΓòÉΓòÉ 538. Error 18 ΓòÉΓòÉΓòÉ

The IF statement should be followed by an open parentheses and the condition to
evaluate the IF statement against. Correct the IF statement and then recompile
the macro.


See also:

    Using the IF/THEN Statements


ΓòÉΓòÉΓòÉ 539. Error 19 ΓòÉΓòÉΓòÉ

You cannot use an ELSEIF or ELSE statement following an ELSE statement.
Rearrange the order of your ELSE and ELSEIF statements and then recompile the
macro.


See also:

    Using the IF/THEN Statements


ΓòÉΓòÉΓòÉ 540. Error 20 ΓòÉΓòÉΓòÉ

The location of the ELSEIF statement is not correct or the macro is not being
controlled by an IF statement at this point. The ELSEIF condition must be prior
to the ELSE and ENDIF statements governed by the IF statement. Make sure the
conditions are positioned correctly and then recompile the macro.


See also:

    Using the IF/THEN Statements




ΓòÉΓòÉΓòÉ 541. Error 21 ΓòÉΓòÉΓòÉ

The location of the ELSE statement is not correct, or the macro is not being
controlled by an IF statement at this time. The ELSE condition must be the last
condition before the ENDIF statement. Make sure the conditions are positioned
correctly and then recompile the macro.



See also:

    Using the IF/THEN Statements




ΓòÉΓòÉΓòÉ 542. Error 22 ΓòÉΓòÉΓòÉ

The location of the ENDIF statement is not correct, or the macro is not being
controlled by an IF statement at this time. The ENDIF statement should follow
all ELSEIF statements. If the ELSE statement is used, the ENDIF statement
should also follow it. Make sure the location of the ENDIF statement is
appropriate and then recompile the macro.



See also:

    Using the IF/THEN Statements




ΓòÉΓòÉΓòÉ 543. Error 23 ΓòÉΓòÉΓòÉ

The location of the NEXT statement is not correct, or the macro is not being
controlled by an FOR statement at this time. Make sure the location of the NEXT
statement is appropriate and then recompile the macro.


See also:

    Using the FOR Statement


ΓòÉΓòÉΓòÉ 544. Error 24 ΓòÉΓòÉΓòÉ

The format of the WHILE is not correct. The syntax of the WHILE statement is
WHILE (expression) statements WEND. Make sure that the WHILE statement is
formatted correctly and then recompile the macro.


See also:

    Using the WHILE Statement


ΓòÉΓòÉΓòÉ 545. Error 25 ΓòÉΓòÉΓòÉ

The location of the CASE statement is not correct. All CASE statements must
appear between a SWITCH and an ENDSWITCH statement. They cannot appear
following the DEFAULT statement. Make sure the SWITCH loop is formatted
correctly and then recompile the macro.


See also:

    Using the SWITCH and CASE Statements


ΓòÉΓòÉΓòÉ 546. Error 26 ΓòÉΓòÉΓòÉ

The SWITCH statement must have a variable name immediately following it that
can be evaluated against the expressions used in the following CASE statements.
Insert a variable name following the SWITCH statement and then recompile the
macro.


See also:

    Using the SWITCH and CASE Statements




ΓòÉΓòÉΓòÉ 547. Error 27 ΓòÉΓòÉΓòÉ

The location of the CASE statement is not correct. All CASE statements must
appear between a SWITCH and an ENDSWITCH statement. They cannot appear
following the DEFAULT statement. Make sure the SWITCH loop is formatted
correctly and then recompile the macro.


See also:

    Using the SWITCH and CASE Statements




ΓòÉΓòÉΓòÉ 548. Error 28 ΓòÉΓòÉΓòÉ

The location of the DEFAULT statement is not correct, or the macro is not
evaluating a SWITCH/ENDSWITCH condition at the location of the DEFAULT
statement. The DEFAULT statement must appear following all CASE statements and
just before the ENDSWITCH statement. Check to make sure the SWITCH loop is
formatted correctly and then recompile the macro.


See also:

    Using the SWITCH and CASE Statements




ΓòÉΓòÉΓòÉ 549. Error 29 ΓòÉΓòÉΓòÉ

The location of the ENDSWITCH statement is not correct, or the macro is not
evaluating a SWITCH/ENDSWITCH condition at the location of the ENDSWITCH
statement. The ENDSWITCH statement must appear following all CASE statements
and the DEFAULT statement. Make sure the SWITCH loop is formatted correctly and
then recompile the macro.


See also:

    Using the SWITCH and CASE Statements




ΓòÉΓòÉΓòÉ 550. Error 30 ΓòÉΓòÉΓòÉ

The location of the BREAK statement is not correct, or the macro is not
evaluating a SWITCH/ENDSWITCH, FOR/NEXT or WHILE/WEND condition at the location
of the BREAK statement. Make sure the BREAK statement is in a FOR/NEXT,
SWITCH/ENDSWITCH or WHILE/WEND loop and then recompile the macro.


See also:

    Using the BREAK Statement
    Using the FOR Statement
    Using the SWITCH and CASE Statements
    Using the WHILE Statement




ΓòÉΓòÉΓòÉ 551. Error 31 ΓòÉΓòÉΓòÉ

The location of the FUNCTION statement is not correct. The FUNCTION statement
must be the very first thing in a macro. If this is not the first macro in the
file, make sure the previous macro is terminated with an END FUNCTION
statement. Make corrections and then recompile the macro.


See also:

    Using the FUNCTION Statement


ΓòÉΓòÉΓòÉ 552. Error 32 ΓòÉΓòÉΓòÉ

The location of the END FUNCTION statement is not correct. The END FUNCTION
statement must be the last statement in a macro. Prior to the END FUNCTION
statement, all IF/THEN, WHILE/WEND, SWITCH/ENDSWITCH and FOR/NEXT loops must be
terminated. Correct errors and then recompile the macro.


See also:

    Using the END FUNCTION Statement
    Using the FOR Statement
    Using the IF/THEN Statements
    Using the SWITCH and CASE Statements
    Using the WHILE Statement


ΓòÉΓòÉΓòÉ 553. Error 33 ΓòÉΓòÉΓòÉ

The syntax you used for the CALL statement is not correct. The correct syntax
is: CALL macroname([parameters]). Make sure that the macroname is followed by
parentheses and that the arguments to the called macro are correct. Correct
errors and then recompile the macro.


See also:

    Using the CALL and CALLI Statements


ΓòÉΓòÉΓòÉ 554. Error 34 ΓòÉΓòÉΓòÉ

The label you referenced in a GOTO statement was not found in the macro. Check
the spelling of the label and make sure that the label is formatted correctly.
Correct errors and then recompile the macro.


See also:

    Using Labels
    Using the GOTO Statement


ΓòÉΓòÉΓòÉ 555. Error 35 ΓòÉΓòÉΓòÉ

The label name you used is already used as a label, or it is used as a variable
name or function name. Select a unique name for the label and then recompile
the macro.


See also:

    Using Labels




ΓòÉΓòÉΓòÉ 556. Error 36 ΓòÉΓòÉΓòÉ

There are too few or too many parameters used for this function. Check the
required syntax, correct the parameters, and then recompile the macro.


ΓòÉΓòÉΓòÉ 557. Error 37 ΓòÉΓòÉΓòÉ

The syntax you used in the DIM statement is not correct. The correct syntax is
DIM arrayname(count), [arrayname(count)...]. Check the statement, correct
errors, and then recompile the macro.


See also:

    Declaring Formal Variables using the DIM Statement


ΓòÉΓòÉΓòÉ 558. Error 38 ΓòÉΓòÉΓòÉ

The syntax you used in the DEFSTR statement is not correct. The correct syntax
is DEFSTR variablename [, variablename...]. Check the statement, correct the
errors, and then recompile the macro.


See also:

    Declaring Formal Variables using the DEFSTR Statement


ΓòÉΓòÉΓòÉ 559. Error 39 ΓòÉΓòÉΓòÉ

Something is wrong with the array reference you used. The array name must be
followed by the element number in parentheses. The element number must be a
number or the expression must evaluate to an integer. Correct the expression
and then recompile the macro.


ΓòÉΓòÉΓòÉ 560. Error 40 ΓòÉΓòÉΓòÉ

You formatted the FOR statement incorrectly. The correct syntax for the FOR
statement is FOR assignment TO expression [STEP expression]. Make sure you
initialize the counting variable in the FOR loop and then recompile the macro.


See also:

    Using the FOR Statement


ΓòÉΓòÉΓòÉ 561. Error 41 ΓòÉΓòÉΓòÉ

You formatted the FOR statement incorrectly. The correct syntax for the FOR
statement is FOR assignment TO expression [STEP expression]. Make sure you
initialize the counting variable in the FOR loop and then recompile the macro.


See also:

    Using the FOR Statement




ΓòÉΓòÉΓòÉ 562. Error 42 ΓòÉΓòÉΓòÉ

The label name you used in the GOTO statement is not a label. Labels cannot be
variable names, function names, or expressions. Make sure that the label name
is correct and then recompile the macro.


See also:

    Using the GOTO Statement
    Using label


ΓòÉΓòÉΓòÉ 563. Error 43 ΓòÉΓòÉΓòÉ

The DECLARE statement is formatted incorrectly. The correct syntax for the
DECLARE statement is DECLARE macroname([arguments]). Make sure the macroname is
followed by parentheses and any arguments. Correct errors and then recompile
the macro.


See also:

     Using the DECLARE Statement


ΓòÉΓòÉΓòÉ 564. Error 44 ΓòÉΓòÉΓòÉ

The macro file you saved does not have any macros in it. If the file is an Ami
Pro document file, you should save it with a .SAM extension. If this file is a
macro file, make sure that the FUNCTION statement is spelled and formatted
correctly. Correct errors and then recompile the macro.


See also:

    Using the END FUNCTION Statement


ΓòÉΓòÉΓòÉ 565. Error 45 ΓòÉΓòÉΓòÉ

The character you typed here does not belong at this point in the macro. Check
the syntax for the function you were trying to perform. If the character should
be part of a string, make sure that there are quotation marks around it.
Correct the statement and then recompile the macro.


ΓòÉΓòÉΓòÉ 566. Error 46 ΓòÉΓòÉΓòÉ

The line the insertion point is on cannot end the way it does. Perhaps there
are too few closing parentheses on the line, or perhaps you forgot to end a
string with quotation marks. Check the statement, make corrections, and then
recompile the macro.


ΓòÉΓòÉΓòÉ 567. Error 47 ΓòÉΓòÉΓòÉ

This indicates the file MACTOKEN.SAM in the AMIPRO directory has become damaged
or is missing. You cannot compile the macro until it has been replaced. Call
Ami Pro support for instructions on how to replace this file.


ΓòÉΓòÉΓòÉ 568. Error 48 ΓòÉΓòÉΓòÉ

The keyname is not the name of a key. Either the keyname is misspelled or you
used a square brace ([) in this string. Check the list of permissible keynames.
If you wanted to type a square brace in the string, use two braces ([[)
instead. Correct errors and then recompile the macro.


ΓòÉΓòÉΓòÉ 569. Error 49 ΓòÉΓòÉΓòÉ

There is a limit of 80 characters that can be used in any single string. You
have exceeded this limit. Shorten the string or break it into two strings and
then recompile the macro.


ΓòÉΓòÉΓòÉ 570. Error 50 ΓòÉΓòÉΓòÉ

One of the macros in this file calls another macro that is not in this file and
does not have the name of another macro file associated with it. Any called
macros must either be in the macro file you are executing or must have
filenames supplied with the macro so they can be found. Make sure the macro
name is spelled correctly and its location is identified correctly. Correct
errors and then recompile the macro.


ΓòÉΓòÉΓòÉ 571. Error 51 ΓòÉΓòÉΓòÉ

One of the macros in this file should be in another macro file, but is not.
When a filename for an macro is specified, Ami Pro searches the macpath
directory, the documents directory, and the Ami Pro program directory for the
specified file. If a full path to the macro is specified, Ami Pro only checks
that path. Check the filename and paths for the called macro, and ensure that
they are correct. Make changes and recompile the macro.



See also:

    Determining the Location of a Macro When it is Run



ΓòÉΓòÉΓòÉ 572. Error 52 ΓòÉΓòÉΓòÉ

There is not enough free memory available to run this macro. Close other open
windows and try running the macro again.


ΓòÉΓòÉΓòÉ 573. Error 53 ΓòÉΓòÉΓòÉ

There is not enough free memory available to run this macro. Close other open
windows and try running the macro again.


ΓòÉΓòÉΓòÉ 574. Error 54 ΓòÉΓòÉΓòÉ

This message indicates that the DDEReceive$ function was not able to execute.
This could be because the DDEInitiate function was not used to set up
communications, or because the DDEInitiate function failed to communicate with
the other OS/2 application. Make sure that you correctly started the DDE
conversation, and that the other application is responding before using the
DDEReceive$ function. Correct errors and then recompile the macro.


See also:

    DDEInitiate
    DDEReceive$


ΓòÉΓòÉΓòÉ 575. Error 55 ΓòÉΓòÉΓòÉ

This message indicates that the DDEReceive$ function was able to communicate
with the other program, but that no data was received from the application by
the DDEReceive$ function. This could be because the other application was not
initialized correctly prior to using the DDEReceive$ function. Check the
parameters required by the other program, and make sure that the DDE
conversation was set up correctly. Correct errors and then recompile the macro.


See also:

    DDEReceive$




ΓòÉΓòÉΓòÉ 576. Error 56 ΓòÉΓòÉΓòÉ

This message indicates that the DDEReceive$ function was not formatted using
the correct parameters. This could be because the ChannelID was not correct, or
because the data requested from the other application was not presented in the
format required by the other application. Check the ChannelID and the format
required for DDE requests from the other application. Correct errors and then
recompile the macro.


See also:

    DDEReceive$




ΓòÉΓòÉΓòÉ 577. Error 58 ΓòÉΓòÉΓòÉ

This message indicates that the DDEExecute function was not able to execute
because the commands used in the DDEExecute function were not correct for the
other application. Check the format required for giving commands to the other
application. Correct and then recompile the macro.


See also:

    DDEExecute


ΓòÉΓòÉΓòÉ 578. Error 59 ΓòÉΓòÉΓòÉ

One of the parameters you used for this function is not correct for the
function. Perhaps the function requires a numeric parameter and you used a
string instead. Check the required parameters, make corrections, and then
recompile and rerun the macro.


ΓòÉΓòÉΓòÉ 579. Error 60 ΓòÉΓòÉΓòÉ

This error message indicates that Ami Pro cannot read the coded instructions to
execute the macro stored in the macro file. If this message should appear, you
should display the macro file, and save it again to regenerate the internal
instructions. If the file saves successfully, and the macro still will not run,
call Ami Pro Customer support for further instructions. When calling support,
make sure you have the error number displayed, and any other parameters
displayed in the error message.


ΓòÉΓòÉΓòÉ 580. Error 61 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic that controls macro execution. If an
internal error should appear, you should first display the macro file. Save the
file again to make sure that the file has not become damaged. If the file saves
successfully and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 581. Error 62 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic that controls macro execution. If an
internal error should appear, you should first display the macro file. Save the
file again to make sure that the file has not become damaged. If the file saves
successfully and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 582. Error 63 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic that controls macro execution. If an
internal error should appear, you should first display the macro file. Save the
file again to make sure that the file has not become damaged. If the file saves
successfully and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 583. Error 64 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, you should first display the macro file. Save
the file again to make sure that the file has not become damaged. If the file
saves successfully, and the macro still will not run, call Ami Pro Customer
support for further instructions. When calling support, make sure you have the
error number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 584. Error 65 ΓòÉΓòÉΓòÉ

Error 65: Internal error, no function number %s Line %1d

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, you should first display the macro file. Save
the file again to make sure that the file has not become damaged. If the file
saves successfully, and the macro still will not run, call Ami Pro Customer
support for further instructions. When calling support, make sure you have the
error number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 585. Error 66 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, you should first display the macro file. Save
the file again to make sure that the file has not become damaged. If the file
saves successfully, and the macro still will not run, call Ami Pro Customer
support for further instructions. When calling support, make sure you have the
error number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 586. Error 67 ΓòÉΓòÉΓòÉ

Error 67: Internal error, logop stack

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still won't run, call Ami Pro Customer support for
further instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 587. Error 68 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still won't run, call Ami Pro Customer support for
further instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 588. Error 69 ΓòÉΓòÉΓòÉ

Error 69: Internal error, mathops stack

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still won't run, call Ami Pro Customer support for
further instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 589. Error 70 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 590. Error 71 ΓòÉΓòÉΓòÉ

This message appears when a macro is running, and an assignment statement or
evaluation of variables attempts to add variables that are not numbers. This
most frequently occurs when a variable which has a string value is added to a
number. Check to make sure that the variables in the statement evaluate to
numbers rather than strings. Remember that an uninitialized variable is equal
to the null string (""), rather than zero. You must specifically initialize
variables in order to guarantee that they will be treated as numeric.

Determine the value of the offending variable and correct its value to ensure
it is numeric. Then recompile the macro and run it again.


ΓòÉΓòÉΓòÉ 591. Error 72 ΓòÉΓòÉΓòÉ

This message appears when a macro is running and a division operation attempts
to divide by zero. Macro execution stops when this message appears. Determine
the variable that is zero at the time of the statement execution. Perhaps you
can evaluate this variable before doing the division and allow the user to
change it, or skip the division if it is zero. Make corrections, recompile, and
then rerun the macro.


ΓòÉΓòÉΓòÉ 592. Error 73 ΓòÉΓòÉΓòÉ

This message appears when a macro is running, and an assignment statement or
evaluation of variables attempts to perform binary arithmetic or multiplication
and division on variables that are not numbers. This most frequently occurs
when a variable that has a string value is divided or multiplied by a number.
This message could also appear if a non-integral number was used as an operand
in a binary operation.

Check to make sure that the variables in the statement evaluate to numbers
rather than strings. Remember that an uninitialized variable is equal to the
null string (""), rather than zero. You must specifically initialize variables
in order to guarantee that they will be treated as numeric. Determine the value
of the offending variable and correct its value to ensure it is numeric. Then
recompile the macro and run it again.


ΓòÉΓòÉΓòÉ 593. Error 74 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 594. Error 75 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 595. Error 76 ΓòÉΓòÉΓòÉ

Internal errors should not appear, and indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 596. Error 77 ΓòÉΓòÉΓòÉ

Internal errors should not appear, and indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 597. Error 78 ΓòÉΓòÉΓòÉ

Internal errors should not appear, and indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 598. Error 79 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 599. Error 80 ΓòÉΓòÉΓòÉ

The index value of an array is larger than the number of elements assigned to
it using the DIM statement. This can occur when a FOR/NEXT loop or WHILE/WEND
loop is used to increment the value of an array index and the element limit in
the DIM statement is exceeded. Macro execution stops when this occurs.
Determine the statement that is causing the index to grow too large, correct
the problem or dimension the array with more elements, and then recompile and
rerun the macro.


See also:

    Declaring Formal Variables Using the DIM Statement
    Using the FOR Statement
    Using the WHILE Statement


ΓòÉΓòÉΓòÉ 600. Error 81 ΓòÉΓòÉΓòÉ

This error message will occur if an Ami Pro function is called at an
inappropriate time. An example of this would be to display the tab ruler in
draft mode, or to create a frame in draft mode.

When this error appears, macro execution is canceled. Determine the Ami Pro
function that could not be executed. Perhaps you can use other Ami Pro commands
to guarantee that the program is in the correct operating mode to let the
function run correctly, or you could jump over the function if the program is
not in the correct mode. Correct the problem, recompile the macro, and then run
it again.


ΓòÉΓòÉΓòÉ 601. Error 82 ΓòÉΓòÉΓòÉ

This message appears when a macro is running, and an ONERROR or ONCANCEL
statement is found in a macro that is called by another macro. This message is
an internal error and should not occur. If this message displays, call Ami Pro
customer support.


See also:

    Using the ONERROR Statement
    Using the ONCANCEL Statement


ΓòÉΓòÉΓòÉ 602. Error 83 ΓòÉΓòÉΓòÉ

The macro used a CALL statement to call another macro, but the called macro was
not in the 'main' macro file or the file referenced in the CALL statement. Any
called macros must either be in the macro file executed by the user, or must
have filenames supplied with the macro so they can be found. Make sure the
macro name is spelled correctly and that its location is identified. Correct
errors and then recompile the macro.


See also:

    Using the CALL and CALLI Statements


ΓòÉΓòÉΓòÉ 603. Error 84 ΓòÉΓòÉΓòÉ

There is not enough free memory available to run this macro. Close other open
windows to reduce memory and try running the macro again.


ΓòÉΓòÉΓòÉ 604. Error 86 ΓòÉΓòÉΓòÉ

The macro was unable to create the menu you requested. This could be because
you used an invalid bar ID or because there was already a menu with the name
you requested. Check the AddMenu statements in the macro. Correct errors and
then recompile the macro.


See also:

    AddMenu


ΓòÉΓòÉΓòÉ 605. Error 87 ΓòÉΓòÉΓòÉ

No more menus could be added because the maximum number of menus on the menu
bar had been reached. You will need to rewrite the macro to include fewer
menus, or use a different menu bar. Make corrections and then recompile the
macro.


ΓòÉΓòÉΓòÉ 606. Error 89 ΓòÉΓòÉΓòÉ

The menu function you wanted could not be completed because of an error
communicating with OS/2. Try closing other applications you may have open. If
you continue to have problems, call Ami Pro customer support.


ΓòÉΓòÉΓòÉ 607. Error 90 ΓòÉΓòÉΓòÉ

The macro was unable to create the menu item you requested. This could be
because you used an invalid bar ID or menu ID, or because there was already a
menu item with the name you requested. Check the AddMenu and AddMenuItem
statements in the macro. Correct errors and then recompile the macro.


See also:

    AddMenu
    AddMenuItem


ΓòÉΓòÉΓòÉ 608. Error 91 ΓòÉΓòÉΓòÉ

No more menu items could be added to the menu because the maximum had already
been reached. You will need to rewrite the macro to include more menus or fewer
items. Correct errors and then recompile the macro.


ΓòÉΓòÉΓòÉ 609. Error 92 ΓòÉΓòÉΓòÉ

There is not enough free memory available to run this macro. Close other open
windows to reduce memory, and try running the macro again.


ΓòÉΓòÉΓòÉ 610. Error 93 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic that controls macro execution. If an
internal error should appear, first display the macro file and then save it to
make sure that the file has not become damaged. If the file saves successfully,
and the macro still will not run, call Ami Pro Customer support for further
instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 611. Error 94 ΓòÉΓòÉΓòÉ

Error 94: Internal Error, symbol number

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic that controls macro execution. If an
internal error should appear, first display the macro file and then save it to
make sure that the file has not become damaged. If the file saves successfully,
and the macro still will not run, call Ami Pro Customer support for further
instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 612. Error 95 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic that controls macro execution. If an
internal error should appear, first display the macro file and then save it to
make sure that the file has not become damaged. If the file saves successfully,
and the macro still will not run, call Ami Pro Customer support for further
instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 613. Error 96 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 614. Error 97 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 615. Error 98 ΓòÉΓòÉΓòÉ

Error 98: Internal Error, grow strings

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 616. Error 99 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file and then save it
to make sure that the file has not become damaged. If the file saves
successfully, and the macro still will not run, call Ami Pro Customer support
for further instructions. When calling support, make sure you have the error
number displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 617. Error 100 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file then save it to
make sure that the file has not become damaged. If the file saves successfully,
and the macro still will not run, call Ami Pro Customer support for further
instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 618. Error 101 ΓòÉΓòÉΓòÉ

Error 101: Internal Error, string frame

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file then save it to
make sure that the file has not become damaged. If the file saves successfully,
and the macro still will not run, call Ami Pro Customer support for further
instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 619. Error 102 ΓòÉΓòÉΓòÉ

Internal errors should not appear. They indicate a problem with the way the
macro was saved, or with the Ami Pro logic which controls macro execution. If
an internal error should appear, first display the macro file then save it to
make sure that the file has not become damaged. If the file saves successfully,
and the macro still will not run, call Ami Pro Customer support for further
instructions. When calling support, make sure you have the error number
displayed and any other parameters displayed in the error message.


ΓòÉΓòÉΓòÉ 620. Error 103 ΓòÉΓòÉΓòÉ

The index value of a global array is larger than the number of elements
assigned to it using the AllocGlobalVar function. This can occur when a
FOR/NEXT loop or WHILE/WEND loop is used to increment the value of an array
index, and the limit set in the AllocGlobalVar function is exceeded. Macro
execution stops when this occurs. Determine the statement thet is causing the
index to grow too large or increase the size of the array in the AllocGlobalVar
function. Correct errors and then recompile and rerun the macro.


See also:

    AllocGlobalVar
    Using the FOR Statement
    Using the WHILE Statement


ΓòÉΓòÉΓòÉ 621. Error 104 ΓòÉΓòÉΓòÉ

There is not enough free memory available to run this macro. Close other open
windows to reduce memory and try running the macro again.


ΓòÉΓòÉΓòÉ 622. Error 105 ΓòÉΓòÉΓòÉ

The global variable ID you used has not been defined. Each global variable is
assigned an ID when it is created, and this ID must be used when that variable
is accessed. Check the ID to make sure it is valid. Correct errors and then
recompile and rerun the macro.


ΓòÉΓòÉΓòÉ 623. Error 106 ΓòÉΓòÉΓòÉ

One of the parameters you used for this function is not correct for the
function. Perhaps the function requires a numeric parameter and you used a
string instead. Check the required parameters. Correct errors and then
recompile and rerun the macro.


ΓòÉΓòÉΓòÉ 624. Error 107 ΓòÉΓòÉΓòÉ

There is not enough free memory available to run this macro. Close other open
windows to reduce memory and try running the macro again.


ΓòÉΓòÉΓòÉ 625. Error 108 ΓòÉΓòÉΓòÉ

The macro you want to edit or run is not an Ami Pro macro file. If it is a
document file, it should have the extension .SAM. If it is a macro file, it
should have the extension .SMM. Make sure the contents of the file are correct.


ΓòÉΓòÉΓòÉ 626. Error 109 ΓòÉΓòÉΓòÉ

The line following an END FUNCTION statement does not have a FUNCTION
statement, or you have used a FUNCTION statement without having ended the
previous function with an END FUNCTION statement. Check the macro, make
corrections, and then recompile.


See also:

    Using the END Function Statement
    Using the FUNCTION Statement


ΓòÉΓòÉΓòÉ 627. Error 110 ΓòÉΓòÉΓòÉ

The offset you provided for a MID$ or strchr function argument is 0. The
minimum possible offset is 1, which will begin the search with the first
character in the string. Change the argument and then recompile the macro.


See also:

    MID$
    strchr


ΓòÉΓòÉΓòÉ 628. Error 111 ΓòÉΓòÉΓòÉ

The location of the THEN statement is not correct. The THEN statement must
follow the condition specified in the IF statement. Check the function, make
corrections, and then recompile the macro.


See also:

    Using the IF/THEN Statements


ΓòÉΓòÉΓòÉ 629. Error 112 ΓòÉΓòÉΓòÉ

One of the functions you are translating from a Record/Play macro to an
editable macro did not translate. Some Ami Pro functions can be recorded and
played back, but cannot be edited. You can recognize these functions in the
editable macro because they will appear as a series of numbers that are
commented out of the macro. If you want to keep the original macro as it was,
do not save the edited version.


ΓòÉΓòÉΓòÉ 630. Error 113 ΓòÉΓòÉΓòÉ

You used the specified item as an argument to a macro function or to another
macro. The item is not a valid variable name or definition substitution, and
cannot be passed to a function. Check the spelling of the variable name or
definition, recompile the macro, and try again.


ΓòÉΓòÉΓòÉ 631. Error 114 ΓòÉΓòÉΓòÉ

You used a function name in your macro that is not a valid macro function or
user defined function. Check the spelling of the built-in function, or make
sure you have correctly declared your user-defined function. Recompile the
macro and try again.


ΓòÉΓòÉΓòÉ 632. Error 115 ΓòÉΓòÉΓòÉ

Ami Pro was unable to access memory needed for the macro. Try running the macro
again; if it fails, then redisplay the macro, resave and run it again. If the
problem continues call Ami Pro Customer Support.


ΓòÉΓòÉΓòÉ 633. Error 116 ΓòÉΓòÉΓòÉ

A string variable for the macro has been corrupted. Check string manipulations
for errors.


ΓòÉΓòÉΓòÉ 634. Error 117 ΓòÉΓòÉΓòÉ

Unable to obtain value of the variable due to unknown type. Converting to code:
2 - Integer
3 - Floating point
4 - %s


ΓòÉΓòÉΓòÉ 635. Error 118 ΓòÉΓòÉΓòÉ

Unable to assign value to a macro variable due to a type mismatch. Converting
to code:
2 - Integer
3 - Floating point
4 - %s


ΓòÉΓòÉΓòÉ 636. Error 119 ΓòÉΓòÉΓòÉ

Ami Pro was unable to obtain enough memory to store a macro variable. Trying
closing one or more of the other OS/2 applications and running the application
again. Also check AllocGlobalVar calls to be sure they are requesting
reasonable amounts of memory.


ΓòÉΓòÉΓòÉ 637. Error 120 ΓòÉΓòÉΓòÉ

The variable passed to a macro function could not be converted to the correct
format for use.


ΓòÉΓòÉΓòÉ 638. Error 121 ΓòÉΓòÉΓòÉ

Internal error: Ami Pro could not access previously stored data. Call Ami Pro
Customer Support.


ΓòÉΓòÉΓòÉ 639. Error 122 ΓòÉΓòÉΓòÉ

Unable to determine the type of variable being substituted.


ΓòÉΓòÉΓòÉ 640. Error 124 ΓòÉΓòÉΓòÉ

Power field is missing correct termination.


ΓòÉΓòÉΓòÉ 641. Error 125 ΓòÉΓòÉΓòÉ

Macro attempted to reference a non-existent field.


ΓòÉΓòÉΓòÉ 642. Error 126 ΓòÉΓòÉΓòÉ

The string was not correctly ended.


ΓòÉΓòÉΓòÉ 643. Error 127 ΓòÉΓòÉΓòÉ

Check to be sure the Call statement is not using a standard macro function
name, and that the MacroName in the Call statement is an existing Ami Pro
macro. See the Call statement documentation for information on syntax.


See also:

    Using the Call and CALLI Statements


ΓòÉΓòÉΓòÉ 644. Error 129 ΓòÉΓòÉΓòÉ

The Style field of the FormatDate function call is invalid. Check to be sure
that it is one of the values listed in the FormatDate  function documentation.


See also:

    FormatDate


ΓòÉΓòÉΓòÉ 645. Error 130 ΓòÉΓòÉΓòÉ

Ami Pro was unable to execute the program. Be sure that the application exists
on your path.


ΓòÉΓòÉΓòÉ 646. Error 131 ΓòÉΓòÉΓòÉ

The variable used is a direct variable. Ami Pro needs an indirect variable that
points to the intended variable. Trying placing an ampersand (&) in front of
the variable and resaving the macro.


ΓòÉΓòÉΓòÉ 647. Error 132 ΓòÉΓòÉΓòÉ

An array variable is needed to run this function.


ΓòÉΓòÉΓòÉ 648. Error 133 ΓòÉΓòÉΓòÉ

Check the function documentation for the correct number of parameters required
for the function.


ΓòÉΓòÉΓòÉ 649. Error 134 ΓòÉΓòÉΓòÉ

Use the pause function for only one macro at a time.


ΓòÉΓòÉΓòÉ 650. Error 135 ΓòÉΓòÉΓòÉ

The format of the dialog box is not correct. See the DialogBox Call information
in the macro documentation for format information.


See also:

    DialogBox


ΓòÉΓòÉΓòÉ 651. Error 136 ΓòÉΓòÉΓòÉ

DIALOG is reserved for use in an Ami Pro macro. Change the name of the variable
to correct the problem.

If you copied the dialog box into an Ami Pro macro, the formatting information
for the dialog box must be contained between the DIALOG and END DIALOG
statements.


See also:

    DialogBox




ΓòÉΓòÉΓòÉ 652. Error 137 ΓòÉΓòÉΓòÉ

END DIALOG is reserved for use in an Ami Pro macro. Change the name of the
variable to correct the problem.

If you copied the dialog box into an Ami Pro macro, the formatting information
for the dialog box must be contained between the DIALOG and END DIALOG
statements.


See also:

    DialogBox


ΓòÉΓòÉΓòÉ 653. Error 138 ΓòÉΓòÉΓòÉ

The ampersand character (&) is used illegally. Try deleting it and use the
remaining variable name. See the Variables section for further information.


See also:

    Using Variables


ΓòÉΓòÉΓòÉ 654. Error 139 ΓòÉΓòÉΓòÉ

The alias created in the DECLARE section for referencing another macro is not
acceptable. See the DECLARE section for further information.


See also:

    Using the DECLARE Statement


ΓòÉΓòÉΓòÉ 655. Error 140 ΓòÉΓòÉΓòÉ

Not Correct parameter or number of parameters in function call.


ΓòÉΓòÉΓòÉ 656. Error 142 ΓòÉΓòÉΓòÉ

Name is a reserved word and can not be used in a DEFINE statement. Check the
DEFINE statements and be sure they each have two parameters and contain no
reserved words.


See also:

    Defining Constants


ΓòÉΓòÉΓòÉ 657. Error 143 ΓòÉΓòÉΓòÉ

The DEFINE statement includes an open parenthesis and expects a matching
closing parenthesis.


See also:

    Defining Constants


ΓòÉΓòÉΓòÉ 658. Error 144 ΓòÉΓòÉΓòÉ

DEFINE statement syntax is not correct. Check the macro documentation for
further information on Defining Constants.


See also:

    Defining Constants


ΓòÉΓòÉΓòÉ 659. Error 145 ΓòÉΓòÉΓòÉ

The replacement string, including inserted parameters must be less than 500
characters.


See also:

    Defining Constants


ΓòÉΓòÉΓòÉ 660. Error 146 ΓòÉΓòÉΓòÉ

The variable name is defined more than once.


See also:

    Defining Constants
    Using Variables


ΓòÉΓòÉΓòÉ 661. Error 147 ΓòÉΓòÉΓòÉ

Macro lines must be less than 255 characters in length.


ΓòÉΓòÉΓòÉ 662. Error 149 ΓòÉΓòÉΓòÉ

Expected closing parenthesis in DEFINE statement.


See also:

    Defining Constants


ΓòÉΓòÉΓòÉ 663. Error 150 ΓòÉΓòÉΓòÉ

The DLL referenced in a DLLCall function was not previously loaded, or the load
was unsuccessful.


See also:

     DLLCall


ΓòÉΓòÉΓòÉ 664. Error 151 ΓòÉΓòÉΓòÉ

The macro was unable to load the DLL. Check to be sure that either the DLL is
in the OS/2 directory or that a full path is used to reference it.


ΓòÉΓòÉΓòÉ 665. Error 152 ΓòÉΓòÉΓòÉ

Ami Pro could not open the macro control file, MACTOKEN.SAM. Check to be sure
that it exists and that it resides in the Ami Pro directory.


ΓòÉΓòÉΓòÉ 666. Error 153 ΓòÉΓòÉΓòÉ

Some functions require indirect variables to return results. This error occurs
when an indirect variable is not passed.


See also:

    Using Variables


ΓòÉΓòÉΓòÉ 667. Error 163 ΓòÉΓòÉΓòÉ

You tried to run a macro written in another version of Ami Pro.  The macro
contains a function that is not supported in this version of Ami Pro. Edit the
macro to contain only functions supported in this version of Ami Pro.


See also:

    Ami Pro Macro Language Contents



ΓòÉΓòÉΓòÉ 668. Ami Pro Macro Language Contents ΓòÉΓòÉΓòÉ

Overview of the Ami Pro Macro Language
Ami Pro Macro Functions Grouped Alphabetically
Ami Pro Macro Functions Grouped by Category
Ami Pro Macro Functions Grouped by Menu
Debugging Macros
Macro Error Messages





ΓòÉΓòÉΓòÉ 669. Overview of the Ami Pro Macro Language ΓòÉΓòÉΓòÉ

Introducing the Ami Pro Macro Language
This section describes how to use the macro language. It also describes the
macro documentation conventions.

Creating, Saving, and Formatting an Ami Pro Macro
This section describes how to create, save, and edit a macro. It also describes
how to format a macro for ease of reading.

Using Macro Programming Statements
This section describes the difference between macro programming statements and
macro functions. It also describes the syntax for each statement. Each macro
must contain at least two programming statements, FUNCTION and END FUNCTION,
and one macro function.

Using Variables
This section describes variables, strings, and the DEFSTR and DIM statements.
It also describes the global variables and the lifetime and visibility of a
variable.

Using Numbers, Strings, and Operators
This section describes the precedence of operators and how to use the various
operator types.

Using Constants
This section describes defined and predefined constants.

Calling Built-In Functions and Other Macros
This section describes calling built-in functions and Ami Pro functions. It
also describes how to determine the location of a macro and using the return
value from called macros.

Integrating REXX Commands
This section describes REXX command files and how to integrate REXX commands
with Ami Pro.

Transferring Program Control
This section describes how to transfer control of a macro to another function
or statement.

Using Results of Evaluations to Control a Macro
This section describes how to use the results of an evaluation to control a
macro.

Using the Lotus Dialog Editor
This section describes the Lotus Dialog Editor.

Using Macro Functions
This section lists each macro function. Each macro contains at least one
function. A macro function must begin with a FUNCTION statement and end with an
END FUNCTION statement. You can have several macro functions within one macro
file.
    Ami Pro Macro Functions Grouped Alphabetically
    Ami Pro Macro Functions Grouped by Category
    Ami Pro Macro Functions Grouped by Menu

Debugging Macros
This section describes error messages that can appear when compiling or running
macros. It also discusses some of the techniques you can use to determine the
cause of the errors, and how you can test your macros to make sure they do what
you want them to.

Macro Error Messages
This section lists each of the error messages that could appear during macro
compilation and execution, along with suggestions for determining the cause of
the problem and how to fix the problem. It does not cover the regular Ami Pro
or OS/2 error messages.

See also:

    Ami Pro Macro Language Contents


ΓòÉΓòÉΓòÉ 670. Introducing the Ami Pro Macro Language ΓòÉΓòÉΓòÉ

This online Help file documents the Ami Pro Macro Language. You can use this
documentation to create your own macros and to customize Record and Play
macros.


You do not need this documentation to use the macro Record and Play functions.
Record and Play functions use the same macro functions described here, but
automatically access these functions.

The Ami Pro Macro Language is similar to BASIC. If you are not a computer
programmer and have not written many macros, you may have difficulty with some
of the information presented in this documentation. You should start with
simple macros, skipping sections that you do not understand. If you are an
experienced computer programmer and have written macros for other programs, use
this documentation to become proficient quickly in the Ami Pro macro language.

Along with the macro functions you automatically access when using power
fields, you can use many other macro functions in power fields. These power
fields macro functions use the same parameters listed in this documentation.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Understanding Macro Documentation Conventions


ΓòÉΓòÉΓòÉ 671. Understanding Macro Documentation Conventions ΓòÉΓòÉΓòÉ

This documentation presents macro statements and functions syntax in a
consistent manner. This should help you understand how to use each statement or
function. The statements and functions use the following format:


Syntax
Function(parm1[ parm2[ parm3...]], 0)
Parm1 is a required parameter.
Parm2 is an optional parameter.
Parm3 is an optional parameter.
0 parameters are required to maintain compatibility with other versions of Ami
Pro.

In this sample function, the function name is first, followed by parameters, if
any, for the function. When you use the function in a macro, you replace the
parameter names with values you provide.

Parameters that are surrounded by square braces ([ ]) are optional unless
otherwise stated. If you use an optional parameter or group of parameters, you
must include all the information shown in the square braces (do not type the
square braces). In this example, Parm2 and Parm3 are both optional.

Parm3 is optional when using Parm2. Parm2 encloses Parm3 within its own set of
square braces. You cannot use Parm3 unless you use Parm2. You do not have to
use Parm3 if you use Parm2.

The three dots following Parm3 show that you can repeat it if needed. If you
can repeat a parameter or portion of a function, the documentation follows the
parameter with three dots. If you repeat a parameter, you must repeat all of
the function that is within the square braces.

Most functions and statements use examples to illustrate how to use the
function in a macro. This documentation shows example macros in the following
style:

Example
FUNCTION test()
TYPE ("This is a test.[ENTER]")
END FUNCTION

Look at the examples for some macro ideas. Most of the example macros
illustrate more than one function or programming concept. Many of the examples
are functional and may perform functions that you can use. If you want to use
an example macro, copy the example to the Clipboard, paste it in an untitled
Ami Pro document, and save it as a macro. Note that this works best if you
maximize the Help window before you copy the example.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating, Saving, and Formatting an Ami Pro Macro


ΓòÉΓòÉΓòÉ 672. Creating, Saving, and Formatting an Ami Pro Macro ΓòÉΓòÉΓòÉ

This section shows you how to create and save Ami Pro macros. While writing
macros, you can format them so they contain a consistent look and feel. This
section also contains information about editing macros and understanding error
messages.


Macros compiled under other versions of Ami Pro may run under OS/2. The first
time you run a macro from another version, Ami Pro for OS/2 recompiles the
macro. Macros compiled using Ami Pro for OS/2 are not compatible with other
versions of Ami Pro. If you want to run macros compiled under other versions of
Ami Pro, you should copy them before using them in Ami Pro for OS/2.

An error message may display if the macro uses functions that are not
supported. You can edit the macro, correct any errors, and recompile it.


See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating and Saving a Macro
    Running Macros Automatically
    Formatting Macros
    Using Comments in a Macro
    Using Multiple Macros in a Single File
    Calling Functions With and Without Parameters


ΓòÉΓòÉΓòÉ 673. Creating and Saving a Macro ΓòÉΓòÉΓòÉ

Type your macro as an Ami Pro document. To save the file as an Ami Pro macro,
choose File Save As and then select Ami Pro Macro as the file type. This saves
the file with .SMM as the extension. If you save the file with the .SAM
extension, Ami Pro does not recognize your file as a macro, and does not
compile it.


When you save a file as a macro, the path changes to the default macro path
that you entered by choosing Tools User Setup Paths. Although you can save
macros to any directory, saving them to the default directory makes them easier
to locate.

When you save a macro file, Ami Pro compiles it into a special format that
allows the macro to run faster. During compilation, Ami Pro checks the macro
for errors. If Ami Pro finds an error, the compilation stops and an error
message displays. The insertion point is at the location of the error so that
you can correct the error. In some cases, the insertion point is on the line
following the error. For example, if you were missing a right parenthesis at
the end of a line, the insertion point is on the next line.

You can create and edit your macro file using the File New, File Open, and File
Save As functions. You can choose Tools Macros Edit from the menu to edit an
existing macro file.

You can edit a macro created with the Tools Macros Record menu function. When
you edit a record and play macro, you may see an error message. This indicates
that one or more of the functions in the record and play macro did not
translate into editable form. A macro created in another version of Ami Pro can
contain functions that are no longer available or are available by using a
different function name. If you want to correct the error, use the new function
name with the correct number of parameters.

You can easily identify untranslated functions. They appear as commented
numbers in the macro file. If you save the macro file, you will lose the
untranslated functions. If you want to keep the original functionality of the
macro, do not save the edited macro.

If you want to reference your macro from other macros, do not place an
exclamation point (!) in the file name when you save your macro. Ami Pro uses
the exclamation point in the syntax of some macro functions.

Ami Pro finds some types of macro errors when the macro runs. These are logic
errors that are not detectable when the macro compiles. For example, your macro
can try to create a frame in draft mode. Ami Pro does not allow this and the
macro results in an error.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating, Saving, and Formatting an Ami Pro Macro
    Running Macros Automatically
    Formatting Macros
    Using Comments in a Macro
    Using Multiple Macros in a Single File
    Calling Functions With and Without Parameters
    Debugging Macros
    Macro Error Messages


ΓòÉΓòÉΓòÉ 674. Running Macros Automatically ΓòÉΓòÉΓòÉ

One of the most useful ways to run a macro is to have it triggered by some
event. Ami Pro provides several ways to automatically run a macro.


Running a macro when you start Ami Pro
There are two ways you can run a macro when Ami Pro starts. Ami Pro runs any
macro file named AUTOEXEC.SMM as it starts. Ami Pro searches for AUTOEXEC.SMM
in the following order:

    Ami Pro program directory
    Any directory specified in the path
    Ami Pro default Macros directory
    Ami Pro Docs directory

You can also specify a series of macros to run by using the _AUTORUN.SMM macro
shipped with Ami Pro. You can specify one macro by choosing Tools User Setup,
choosing Macros, and specifying the macro to run. You can specify several
macros by choosing Tools Macros Playback, selecting AUTORUN.SMM, and specifying
the macros to run.

Running a macro when you exit Ami Pro
There are two ways you can run a macro when exiting Ami Pro. Ami Pro runs any
macro file named AUTOEXIT.SMM as it shuts down. Ami Pro searches for
AUTOEXIT.SMM in the following order:

    Ami Pro program directory
    Any directory specified in the path
    Ami Pro default Macros directory
    Ami Pro Docs directory

You can also specify a macro by choosing Tools User Setup, choosing Macros, and
specifying the macro to run.

Running a macro when you open or close a file
You can run a macro any time you open or close a document. Ami Pro runs any
macro file named AUTOOPEN.SMM when you open a document. Ami Pro runs any macro
file named AUTOCLOS.SMM when you close a document.

Ami Pro searches for AUTOOPEN.SMM and AUTOCLOS.SMM in the following order:
    Ami Pro default Macros directory
    Ami Pro program directory
    Any directory specified in the path
    Ami Pro Docs directory

Running a macro when you create a new document
You can run a macro any time you create a new document using File New. Ami Pro
runs any macro file named AUTONEW.SMM when you create a new document. Ami Pro
searches for AUTONEW.SMM in the following order:
    Ami Pro default Macros directory
    Ami Pro program directory
    Any directory specified in the path
    Ami Pro Docs directory

Running a macro when you open or close a specific document
You can run a macro any time you open or close a specific document. Open the
document you want to attach a macro to, choose Tools Macros Edit, and choose
Assign. Specify the macros to execute whenever this document is opened or
closed and check the box. Next time you open or close this document, Ami Pro
runs the macros you specify.

Running a macro when you choose a specific style sheet

You can run a macro any time you create a new document using a specific style
sheet. Choose Style Save as a Style Sheet, specify a macro to execute whenever
this style sheet is used, and check the box. Next time you choose File New and
select this style sheet, Ami Pro runs the macro you specify.

Running a macro when you select a frame
You can assign a macro to any frame. The frame then becomes a button and runs
the macro assigned to it whenever it's selected. Select the frame, choose Frame
Modify Frame Layout, specify a macro, and check the box. You must also choose
File Doc Info and check the box beside Run frame macros.

Running a macro when you update power fields
You can run a macro whenever you update power fields. Choose Edit Power Fields
Insert, choose CALL, and specify a macro. Next time you update power fields,
Ami Pro runs the the macro you specify.

Using multiple autorun macros
When you set multiple autorun macros they execute in the following order:
    Macros assigned to the style sheet that loads when Ami Pro is started run
    first.
    AUTOEXEC.SMM, including any other macros it may call.
    Any macros listed in _AUTORUN.SMM run in the order in which they are
    listed.

In addition, the following macros run at the specified times:
    AUTONEW.SMM runs before a macro attached to the particular style sheet.
    AUTOOPEN.SMM runs before a macro assigned to that document.
    AUTOEXIT.SMM runs after any macro specified for Program Exit under User
    Setup.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating, Saving, and Formatting an Ami Pro Macro



ΓòÉΓòÉΓòÉ 675. Formatting Macros ΓòÉΓòÉΓòÉ

You can type your macro with any combination of fonts, paragraph styles, and
text attributes to make the macro more readable. Ami Pro saves attribute and
paragraph style information with the document containing your macro, but none
of the attributes or paragraph styles affect how your macro plays.


When you use numbers in a macro, you can use the hexadecimal equivalent by
preceding the number with "0x" or "0X".

In many of the macro functions, length and size are in twips. There are 1440
twips in an inch (1 inch=1440 twips). Multiply the desired inches by 1440 to
determine the size in twips.

Type each macro statement on a single line to improve readability. Use tabs or
indented paragraph styles to indent portions of a macro that are parts of a
FOR/NEXT loop or an IF/THEN statement.

You can use a double quotation mark (") at the beginning and end of text to
represent a string or two double quotation marks ("") to include a single
double quotation (") as part of the string.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating, Saving, and Formatting an Ami Pro Macro
    Creating and Saving a Macro
    Running Macros Automatically
    Using Comments in a Macro
    Using Multiple Macros in a Single File
    Calling Functions With and Without Parameters






ΓòÉΓòÉΓòÉ 676. Using Comments in a Macro ΓòÉΓòÉΓòÉ

A comment is non-executable text you can insert in a macro. You can use
comments to document what a macro does.


Any text that follows a single quotation mark (') and any text outside a
FUNCTION/END FUNCTION pair is treated as a comment. The single quotation mark
can be at the beginning of a paragraph, causing Ami Pro to skip the entire
paragraph. It can also follow a statement in a paragraph, causing Ami Pro to
skip the rest of the paragraph.

Example
The following macro illustrates the use of comments:
FUNCTION showcomment()
'This macro illustrates the use of comments in a macro
var = "Print Me"     ' this line assigns a value to a variable
var1 = "Print Me, Too"
' this line also assigns a value to a variable, and this comment is longer than
a single line of text.
TYPE ("{var}") ' TYPE ("{var1}") var 1 is a comment and not printed.
END FUNCTION

The output of the macro is as follows.
"Print Me"

Note that the second TYPE function is not acted on because it is part of a
comment.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating, Saving, and Formatting an Ami Pro Macro
    Creating and Saving a Macro
    Running Macros Automatically
    Formatting Macros
    Using Multiple Macros in a Single File
    Calling Functions With and Without Parameters






ΓòÉΓòÉΓòÉ 677. Using Multiple Macros in a Single File ΓòÉΓòÉΓòÉ

You can have more than one macro in a macro file. Keeping related macros in the
same file improves the speed of macro playback. To have more than one macro in
a macro file, use several FUNCTION and END FUNCTION pairs within a single file.
The macro function that executes when you run the macro is the first macro in
the macro file.


Text that appears outside the FUNCTION/END FUNCTION pair is comments and
therefore ignored; however, Ami Pro recognizes the DECLARE and DEFINE
statements. Use the comment format to describe the functionality of the macro.

Example
The following macro functions ask the user to provide two numbers. The function
average uses the numbers to obtain an average, and the function main displays
the results.
FUNCTION main()
num1 = Query$ ("Type the first number:")
num2 = Query$ ("Type the second number:")
result = CALL average (num1, num2)
message ("The average of the two numbers is {result}")
END FUNCTION

This subroutine calculates the average of two passed numbers.
FUNCTION average (p1, p2)
average = ((p1 + p2) / 2)
END FUNCTION

The function main asks for the two numbers to average using the Query$
function. It then calls the function average to determine the average and
displays the result using the Message function. The function average returns
the result to the main function by assigning the average to the variable
average within the called macro. If the return value is different from the name
of the function, use the RETURN statement.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating, Saving, and Formatting an Ami Pro Macro
    Creating and Saving a Macro
    Running Macros Automatically
    Formatting Macros
    Using Comments in a Macro
    Calling Functions With and Without Parameters




ΓòÉΓòÉΓòÉ 678. Calling Functions With and Without Parameters ΓòÉΓòÉΓòÉ

You can call most functions with or without parameters. If you do not pass
parameters, Ami Pro displays the dialog box as if the user accessed the
function through the menu system.


You can access some functions that are several levels deep in the menu system.
For example, there is a command to insert a glossary record. Executing this
function brings up the Insert Glossary Record dialog box.

This language includes macro menu commands so you can develop replacement menu
bars for Ami Pro. You can use the menu only commands in these macros.

Several functions  generate child processes of Ami Pro. These include the File
Management, Help, and System Setup functions. When you use these functions, the
appropriate window opens and the program runs--therefore, you should end the
macro immediately after the function call or use a pausing function. If your
macro executes statements after one of these windows opens, the Ami Pro window
may display on top of the function's window.

Example
FileOpen("DOC.SAM", 1, "") ' opens and displays the file DOC.SAM
FileOpen ' brings up the File Open dialog box

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Creating, Saving, and Formatting an Ami Pro Macro
    Creating and Saving a Macro
    Running Macros Automatically
    Formatting Macros
    Using Comments in a Macro
    Using Multiple Macros in a Single File


ΓòÉΓòÉΓòÉ 679. Using Macro Programming Statements ΓòÉΓòÉΓòÉ

The macro language consists of a rich variety of programming statements that
control the action of the macro. By combining the programming statements with
the built-in macro functions and the Ami Pro functions, you can create powerful
tools for use with Ami Pro.


There are three components of the macro language: programming statements, macro
functions, and Ami Pro macro functions.

Programming Statements
This section documents programming statements that you can use to control your
macro:
    ALIAS
    BREAK
    CALLI
    CALL
    CASE
    DECLARE
    DEFAULT
    DEFINE
    ELSEIF
    ELSE
    END FUNCTION
    ENDIF
    ENDSWITCH
    EXIT FUNCTION
    FOR
    FUNCTION
    GOTO
    IF
    NEXT
    ONCANCEL
    ONERROR
    STEP
    SWITCH
    THEN
    TO
    Using LABELS
    WEND
    WHILE

Macro Functions
These functions allow you to interact with the macro user, interact with other
applications, and get and send information from and to Ami Pro. These functions
are generally not available in Ami Pro menus.

Variables:
    DEFSTR
    DIM

Numbers, Strings, and Operators:
    Bitwise AND
    Bitwise OR
    Logical AND
    Logical OR
    Logical NOT

Program Control:
    RETURN


Ami Pro Macro Functions
These functions are those that you can execute in Ami Pro by using the menu bar
and dialog boxes.

See also:

    Ami Pro Macro Language Contents
    Overview of the Ami Pro Macro Language
    Ami Pro Macro Functions Grouped Alphabetically
    Ami Pro Macro Functions Grouped by Category
    Ami Pro Macro Functions Grouped by Menu
    Using Variables



ΓòÉΓòÉΓòÉ 680. Using the BREAK statement ΓòÉΓòÉΓòÉ

Looping allows repetitive tasks to be coded once and executed repeatedly until
a  certain condition becomes true or until an event occurs. The BREAK statement
allows control to pass out of the loop, and ends the action of the FOR/NEXT,
SWITCH/CASE, and WHILE/WEND statements.


When in a FOR/NEXT loop, there are times when the loop should be ended before
the total number of repetitions specified in the FOR statement. In a
SWITCH/CASE loop, there are times when only certain statements should be
processed for a matching case, based on some other variable. Similarly, there
are times when the macro needs to break out of a WHILE/WEND loop.

Syntax
BREAK

Example
This example bolds every occurrence of the word "and".
FUNCTION BoldWord()
TYPE("[CTRLHome]") ' go to the beginning of the document
WHILE(TRUE) ' create a loop
findit = Replace("", "", "", "and", "") ' search for "and"
IF findit <> 1 ' if we can't find the word, break out of the loop
BREAK
ENDIF
Bold()
TYPE("[ESC]") ' deselect the word
WEND
END FUNCTION

Line 2 returns the cursor to the beginning of the document. Line 3 begins the
WHILE loop that always executes because the value is TRUE. Line 4 finds the
next occurrence of "and". Line 5 evaluates the variable findit with TRUE. If
findit is TRUE, Line 8 bolds the word "and". Line 9 deselects the word. Line 10
ends the loop and returns control to Line 3 and the loop continues. If the
variable findit is FALSE, the IF statement will evaluate Line 6 and the macro
stops the loop. The macro runs the next line, in this case Line 11 is an END
FUNCTION.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Using the FOR Statement
    Using the SWITCH and CASE Statements
    Using the WHILE Statement



ΓòÉΓòÉΓòÉ 681. Using the CALL and CALLI statements ΓòÉΓòÉΓòÉ

The CALL and CALLI statements execute a macro function from another macro file.
You can use the CALL statement when you know the name of the macro to execute
when the macro compiles. You can use the CALLI statement when you do not know
the name of the macro until you run the macro.


Syntax
CALL [[Drive:Path\]MacroFile!]Function([Parm1][[,] Parm2...])
drive, path, and MacroFile are the drive letter, full path, and macro file name
that contain the called macro.
MacroName is the name of the macro to execute.
Parm1 and parm2 are the parameters to pass to the macro.
You must supply the parentheses even if you are not passing any parameters to
the called function. For example, CALL mymacro.smm!myfunction()

Syntax
CALLI Variable ([Parm1][[,] Parm2...])
variable is a string variable that evaluates to the name of a macro. The name
of the macro may contain the drive, path, and file name as outlined above for
the CALL statement.
Parm1 and Parm2 are the parameters to pass to the macro.

You must supply the parentheses even if you are not passing any parameters to
the called function. For example, CALLI mytestfunction(). The parameters given
can be any expression.

You must follow the drive, path, and macro file name, if given, by an
exclamation point and the name of the macro. You do not need the drive, path,
and macro file name if the called macro is in the same file as the calling
macro. If given, Ami Pro looks for the macro in the location of the macro path.
If no path is given, Ami Pro searches the macro directory, the document
directory, and the Ami Pro directory for the called macro.

If the disk location of the called macro is not on one of the locations in the
macro search path, and must be determined at runtime, the CALLI statement
should be used instead. The only difference between the CALL and the CALLI
statements is that the macro name and path can be specified in a variable when
the CALLI statement is used, while they must be specified explicitly when using
the CALL statement.

Example
The following example illustrates the use of the DECLARE, CALL and CALLI
statements. This macro determines either the number count of the letters in a
word, or the number of digits in a number.

DECLARE getopt()
' declare this function so we can use it later

FUNCTION main()
string = Query$ ("Type a word or a number:")
flag = getopt()
' since declared, do not have to use CALL statement
 IF (flag = 6)
   result=CALL sub1 (string)       ' since macro is here, just use CALL
 statement
   message ("There are {result} letters in {string}.")
 ELSE
   thismacro=GetRunningMacroFile$()
   macname = strcat$(thismacro, "!SUB2")   ' put into var
   result=CALLI macname (string)     ' use variable cause do not know filename
   message ("There are {result} digits in {string}.")
 ENDIF
 END FUNCTION

 FUNCTION sub1 (string)     ' this is in original file
 sub1 = LEN(string)
 END FUNCTION

 FUNCTION getopt()   ' this is in original file
 getopt = MultiDecide ("Choose Yes for letters; No for numbers", 35)
 END FUNCTION

 FUNCTION sub2 (string)     ' this is called by the CALLI funciton in Main
 numcount = 0
 FOR count = 1 to LEN(string)
   c = MID$(string, count, 1)
   IF (isnumeric(c))
    numcount = numcount +1
   ENDIF
 NEXT
 sub2 = numcount
 END FUNCTION

This macro examines a word or number and returns the total number of characters
or digits.  In the main function, line 3 retrieves a string.  The getopt
function, declared on Line 1, is used on Line 4 just as if it were an Ami Pro
function. This function presents a MULTIDecide box to determine if the string
is a word or a number.  If the MULTIDecide box returns a "yes," Line 6 calls
the sub1 function, which returns the number of characters in the string.  In
Line 7, the returned value is displayed.  Otherwise, in line 10 the macro calls
the variable function (which in this case evaluates to the current macro
filename followed with "!sub2").  Sub2 computes and returns the number of
digits in the string. In Line 12, the returned value is displayed.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements



ΓòÉΓòÉΓòÉ 682. Using the DECLARE statement ΓòÉΓòÉΓòÉ

You can use DECLARE to identify callable macro functions before you call the
macro.


DECLARE pre-defines a function for the macro compiler. DECLARE allows you to
call a non-defined macro function without using a CALL statement.

Syntax
DECLARE [FileName!]MacroName([parm1[, parm2...]])[, ALIAS ShortName]
FileName is the optional file name of the function to be pre-defined. If not
specified, the macro is assumed to be in the current file.
MacroName is the name of the macro to be predefined.
Parm1 and parm2 are prototypes of the parameters that pass to the macro when
called. They must be variable names, but you do not need to declare them.
ALIAS is a reserved word that takes the parameter ShortName if used. This
optional specification allows you to assign the macro function that has been
pre-defined on this line to a shorter name.
Any parameters must be specified so the compiler knows how many to expect.

Using the DECLARE statement does not cause the macro referenced to execute; it
simply identifies a macro that you can use within the calling macro. Once
declared, a macro can execute from another macro by typing its name and
parameters.

Example
The following example illustrates the use of the DECLARE, CALL and CALLI
statements. This macro determines either the number count of the letters in a
word, or the number of digits in a number.

 DECLARE getopt()    ' declare this function so we can use it later

 FUNCTION main()
 string = Query$ ("Type a word or a number:")
 flag = getopt()
 ' since declared, do not have to use CALL statement
 IF (flag = 6)
   result=CALL sub1 (string)       ' since macro is here, just use CALL
 statement
   message ("There are {result} letters in {string}.")
 ELSE
   thismacro=GetRunningMacroFile$()
   macname = strcat$(thismacro, "!SUB2")   ' put into var
   result=CALLI macname (string)     ' use variable cause do not know filename
   message ("There are {result} digits in {string}.")
 ENDIF
 END FUNCTION

 FUNCTION sub1 (string)     ' this is in original file
 sub1 = LEN(string)
 END FUNCTION

 FUNCTION getopt()   ' this is in original file
 getopt = MultiDecide ("Choose Yes for letters; No for numbers", 35)
 END FUNCTION

 FUNCTION sub2 (string)     ' this is called by the CALLI funciton in Main
 numcount = 0
 FOR count = 1 to LEN(string)
   c = MID$(string, count, 1)
   IF (isnumeric(c))
    numcount = numcount +1
   ENDIF
 NEXT
 sub2 = numcount
 END FUNCTION

This macro examines a word or number and returns the total number of characters
or digits.  In the main function, line 3 retrieves a string.  The getopt
function, declared on Line 1, is used on Line 4 just as if it were an Ami Pro
function. This function presents a MULTIDecide box to determine if the string
is a word or a number.  If the MULTIDecide box returns a "yes," Line 6 calls
the sub1 function, which returns the number of characters in the string.  In
Line 7, the returned value is displayed.  Otherwise, in line 10 the macro calls
the variable function (which in this case evaluates to the current macro
filename followed with "!sub2").  Sub2 computes and returns the number of
digits in the string. In Line 12, the returned value is displayed.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements



ΓòÉΓòÉΓòÉ 683. Using the DEFINE statement ΓòÉΓòÉΓòÉ

You can use the DEFINE statement to do a simple token replacement ("this" item
for "that" item). A more powerful use of the DEFINE statement is to replace
parameters.


Syntax
DEFINE identifier([optional descriptive parameters]) replacement([parameters])

Example
This example allows you to replace a descriptive name with a number.
DEFINE ALL 1
DEFINE JUSTONE 2
MyFunction(ALL)
    ..........
FUNCTION MyFunction(type)
    ..........
if (type=ALL)
elseif(type=JUSTONE)

When the macro runs, it replaces ALL and JUSTONE by 1 and 2.

This example allows you to replace a descriptive name with parameters.

DEFINE Findit() Replace(0,0,4,%1,0)
Then you enter the text to replace.
Findit("text")

When the macro is compiled, Findit("text") is replaced with Replace
(0,0,4,"text",0). The replacement uses the DOS batch file notation for
parameters. If you have more than one parameter they would be %2, %3, etc. You
can use these more than once and in any order. For more information about
parameters, see your DOS manual.

When Ami Pro encounters the DEFINE, it remembers the complete replacement. When
the next occurrence happens, parentheses surround the parameters and separate
the parameters by white characters or commas. Parameters can be either quoted
strings, a string surrounded by parentheses, or any non-white sequence of
characters. Once Ami Pro identifies the parameters, it scans the replacement
for %1, %2, etc., and replaces the parameters. The whole string is then
re-parsed. The total replacement, after parameter substitution, must be less
than 500 characters.

An example of calling DLL functions would be:
DllCall(Dllid,p1,p2)

or use DEFINE:
DEFINE LookUp() DLLCall(Dllid,%1,%2)

It could be:
LookUp(p1,p2)

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements



ΓòÉΓòÉΓòÉ 684. Using the END FUNCTION Statement ΓòÉΓòÉΓòÉ

All Ami Pro macro language routines are contained within functions. When you
run a macro, you are actually telling Ami Pro to run the first function in the
macro file.


A macro function must start with a FUNCTION statement and stop with an END
FUNCTION statement. Each macro file must contain at least one function, but you
can have several macro functions within one macro file.

The END FUNCTION statement defines the end of a macro function. It causes a
return to the calling macro or the end of a macro play.

Syntax
END FUNCTION

Every macro must have an END FUNCTION statement as the last line of the macro.
If the macro has more than one exit point, use the EXIT FUNCTION statement at
the other exit points in the macro.

Example
The following example calculates the average of two numbers and returns the
result to the calling macro:
 FUNCTION average (p1, p2)
 average = ((p1 + p2) / 2)
 END FUNCTION

Line 1 assigns the name average to this macro. The calling macro passes the
arguments p1 and p2 to this macro. The second line of the macro calculates the
average and the last line ends the function.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Using the EXIT FUNCTION Statement
    Using the FUNCTION Statement


ΓòÉΓòÉΓòÉ 685. Using the EXIT FUNCTION statement ΓòÉΓòÉΓòÉ

The EXIT FUNCTION statement allows a macro to stop before reaching the end of
the macro. A macro usually ends with an END FUNCTION statement. You can use the
EXIT FUNCTION statement when there are several different exit points to the
same macro. While there can be only one END FUNCTION statement in a macro
function, there can be multiple EXIT FUNCTION statements.


Syntax
EXIT FUNCTION

Example
The following example uses the EXIT FUNCTION statement to exit the macro before
the macro ends:
 FUNCTION saveit()
 ' This macro saves a file only if the file has changed. Otherwise, it cancels
the save
 stat = FileChanged (0, 0)  ' get file changed status
 IF stat = false     ' file hasn't changed
    EXIT FUNCTION           ' quit; no need to save
 ENDIF
 save()       ' save file
 END FUNCTION        ' end it

In this example, the EXIT FUNCTION statement in line 5 exits the macro if the
file does require saving. The END FUNCTION statement in line 8 exits the macro
following the saving of the file.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Using the END FUNCTION Statement
    Using the FUNCTION Statement


ΓòÉΓòÉΓòÉ 686. Using the FOR statement ΓòÉΓòÉΓòÉ

Looping allows repetitive tasks to be coded once and executed repeatedly until
a  certain condition becomes true or until an event occurs.  You can use
FOR/NEXT statements to specify how many times the code inside the loop
executes. The FOR statement executes a series of steps one or more times or
skip the program steps. When the loop is finished, code execution continues
with the line after NEXT.


When Ami Pro encounters a FOR statement, the variable specified in the
assignment initializes to the value of the assignment. Ami Pro compares this
variable to expression1. If the variable is less than or equal to expression1,
Ami Pro executes the program steps between the FOR statement and the NEXT
statement. If the result of the comparison is false, the program continues with
the first statement following the NEXT statement.

When the macro executes the NEXT statement, control returns to the FOR
statement. The variable increments by the amount specified in expression2. If
there is not an expression2, the variable increments by 1. Ami Pro compares the
new value of the variable to expression1. If the two values are not equal,
program steps execute again. This process continues until the value of the
variable is greater than expression1 and program control passes to the first
statement following the NEXT statement.

Syntax
FOR Assignment TO Expression1
[STEP Expression2]
   Program statements
NEXT
Assignment is an assignment of value to a single element variable.
Expression1 is an expression to which the value of the single element variable
is compared.
Expression2 is an expression that is added to the single element variable once
for each loop iteration.
Program statements are the macro statements executed if the value of the single
element variable is less than expression1 at the beginning of each loop.

Example
The following example illustrates the use of the FOR and NEXT statements:
 FUNCTION typename()
 FOR loop1 = 1 to 5
   TYPE("Ami Pro ")
 NEXT
 END FUNCTION

Line 2 initializes the variable loop1 to 1. Line 3 types "Ami Pro " to the
screen, excluding the quotation marks. Line 4 transfers the control back to
Line 2. Line 2 checks to see if loop1 is equal to 5. If loop1 is less than 5,
the macro increments loop1 by 1 and continues to Line 3. The loop continues for
a total of 5 iterations. When loop1 is equal to 5, the macro ends.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements


ΓòÉΓòÉΓòÉ 687. Using the FUNCTION Statement ΓòÉΓòÉΓòÉ

All Ami Pro macro language routines are contained within functions. When you
run a macro, you are actually telling Ami Pro to run the first function in the
macro file.


A macro function must start with a FUNCTION statement and stop with an END
FUNCTION statement. Each macro file must contain at least one function, but you
can have several macro functions within one macro file.

The FUNCTION statement defines the beginning of a macro, names the macro, and
defines any arguments passed to the macro.

You can pass as many arguments as needed to a macro or none at all. You cannot
pass arguments to a macro started through the Macro Play function or through a
shortcut key. You can only pass arguments to macros you call as functions of
other macros. Argument names must be character strings, numbers, or defined
variable names.

Syntax
FUNCTION Name ([Argument1][[,] Argument2...])
Name is the name of the macro. It must begin with a letter, but can contain
both numbers and letters.
Argument1 and Argument2 are variables that are passed to the macro when the
macro runs.

Example
The following example calculates the average of two numbers and returns the
result to the calling macro:
 FUNCTION average (p1, p2)
 average = ((p1 + p2) / 2)
 END FUNCTION

Line 1 assigns the name average to this macro. The calling macro passes the
arguments p1 and p2 to this macro. The second line of the macro calculates the
average and the last line ends the function.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    String Macro Functions
    Using the END FUNCTION Statement
    Using the EXIT FUNCTION Statement
    Using Variables


ΓòÉΓòÉΓòÉ 688. Using the GOTO statement ΓòÉΓòÉΓòÉ

In a macro function, the lines of code are usually executed in the order they
appear. You can divert the flow of execution through unconditional branching.
You can use a GOTO statement to unconditionally transfer control from one
location to another in a macro file. The location that the GOTO statement
transfers control to must be in the same macro as the GOTO statement and
defined by a Label.


Using GOTO statements to control program flow makes a macro more difficult to
read, and increases the risk of causing an error if you edit the macro. You can
usually eliminate the need for GOTO by using other macro programming statements
and subroutines.

Syntax
GOTO Label
Label is a label name defined elsewhere in the macro program. When you use it
in the GOTO statement, do not type a colon following the label name.

Example
The following example shows the use of the GOTO and Label statements:
 FUNCTION main()
 string = Query$ ("Type a word or a number:")
 flag = (MultiDecide ("Choose Yes for letters; No for numbers", 35))
 IF (flag = 6) GOTO letters
 ELSEIF (flag = 7) GOTO numbers
 ENDIF
 letters:
 result = LEN(string)
 message ("There are {result} letters in {string}.")
 GOTO endit
 numbers:
 numcount = 0
 FOR count = 1 to LEN(string)
    c = MID$ (string, count, 1)
    IF (isnumeric(c))
       numcount = numcount +1
    ENDIF
 NEXT
 message ("There are {numcount} digits in {string}.")
 endit:
 END FUNCTION

This macro is a variation of the example used to illustrate the CALL and
DECLARE statements. Instead of using subroutines to get the user's choice of
counting letters and numbers and to do the count, this macro first determines
the user's choice by using the Query$ function in line 2. If the user chooses
letters, the GOTO statement in line 4 transfers control to the letters label in
line 7. If the user chooses numbers, the program uses the GOTO statement in
line 5 to jump to the numbers label in line 11.

The macro requires a GOTO statement in line 10 to jump to the end of the macro
so that the letters option does not also execute the numbers option.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements


ΓòÉΓòÉΓòÉ 689. Using the IF/THEN statements ΓòÉΓòÉΓòÉ

In a macro function, the lines of code are usually executed in the order they
appear. You can divert the flow of execution through unconditional branching.
The IF statement evalutes an expression and causes lines of code to execute
based on the result of the evaluation.


When a macro encounters an IF statement, the macro evaluates the condition
specified in condition1. If the condition evaluates to TRUE, Program step 1
executes and control passes to the first program line beyond the ENDIF. If the
condition is FALSE, the macro evaluates to condition2.

If this condition is TRUE, then Program step 2 executes and control passes to
the first program line beyond the ENDIF. The macro evaluates subsequent
ELSEIF's (if present) until one of the ELSEIF conditions is TRUE and its
statements execute or the ELSE statement, if present, executes.

Syntax
IF Condition1 [THEN]
Program step 1
[ELSEIF Condition2 [THEN]
Program step 2]...
[ELSE
Program step 3]
ENDIF
Condition 1 is an expression that causes program step 1 to execute if it
evaluates to TRUE.
Program step 1 is a series of macro statements that execute if condition1
evaluates to TRUE.
Condition 2 is an expression, that causes program step 2 to execute if it
evaluates to TRUE.
Program step 2 is a series of macro statements that execute if condition2
evaluates to TRUE and previous conditions are FALSE.
Program step 3 is a series of macro statements that execute if none of the
previous conditions were TRUE.

Example
The following example deletes two carriage returns in a row in a document. This
allows removal of the blank line between paragraphs. It uses the IF statement
to find two carriage returns in a row.
 FUNCTION delcrs()
 TYPE ("[ctrlhome]") ' go to top of file
 loop:
 TYPE ("[ctrldown]") ' to next RETURN symbol
 c = CurChar$()
 TYPE ("[RIGHT]")
 IF (AtEOF()) ' at end of file?
    EXIT FUNCTION 'end macro execution
 ELSEIF (c = CurChar$()) ' look for two in a row
    TYPE ("[DEL]")
 ENDIF
    GOTO loop
 END FUNCTION

The macro starts by going to the beginning of the file in line 2. It then moves
to the end of the first paragraph in line 4. In line 5, the macro stores in the
variable c the value of the character under the insertion point. The insertion
point then advances one position in line 6. The IF statement in line 7
determines if the macro reached the end of the file. If so, the macro exits in
line 8. If not, the ELSEIF statement in line 9 compares the value of the
character at the insertion point position with the value of the previously
stored character c. If they are the same (the condition is TRUE), line 10
deletes the second return symbol. There is no ELSE condition in this IF
statement, since we are not interested in any other characters besides return
symbols and the end of the file. Therefore, control passes through the ENDIF
statement and jumps to the label LOOP in line 3, where the sequence repeats.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements



ΓòÉΓòÉΓòÉ 690. Using labels ΓòÉΓòÉΓòÉ

A label is a position marker which you can refer to. You can use a label to
define the location where the macro transfers control from the GOTO statement.


Syntax
Label:
Label is a single word followed immediately by a colon. Labels cannot be
function names or statement names.

Example
The following shows some permissible label names:
TopOfLoop:
Any1:
proceed:

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Using the GOTO Statement


ΓòÉΓòÉΓòÉ 691. Using the ONCANCEL statement ΓòÉΓòÉΓòÉ

The user can cancel the running of a macro by typing a key while the macro is
playing back or by choosing Cancel in the Query$ function dialog box. Normally,
canceling the macro terminates the macro with no notice to the macro user. By
using the ONCANCEL statement, you can inform the user that the macro has
canceled or you can cause the execution of the macro to continue elsewhere.


If the macro encounters an error or cancel condition, Ami Pro looks for an
ONCANCEL statement in the currently running macro function. If Ami Pro finds no
ONCANCEL, it searches succeeding parent functions for an ONCANCEL statement,
until it encounters the main function. This means that each macro function can
have its own error processing.

If an error occurs in a subroutine, and the macro processes it in that routine,
Ami Pro does not search any farther for other ONCANCEL statements. You should
ensure that parent functions correctly handle error conditions.

When using the ONERROR and ONCANCEL statements, make sure that they are at the
beginning of the macro. If an error occurs before these statements, control may
not transfer to the error or cancellation routines.

Syntax
ONCANCEL Label
Label is the name of a label to which control transfers in case the user
cancels the macro.

Example
The following is an example of the ONERROR and ONCANCEL statements:
 FUNCTION main()
 ONERROR ErrorRoutine 'set error routine
 ONCANCEL CancelRoutine 'set cancel routine
 Query$ ("Choose OK or CANCEL.") ' set up routine
 CALL notthere() ' this causes an error, since macro not there
 GOTO endit
 CancelRoutine:
 message ("You canceled the macro.")
 GOTO endit
 ErrorRoutine:
 message ("There has been a macro error.")
 endit:
 END FUNCTION

This macro defines program locations for error and cancel handling in lines 2
and 3. It then asks the macro user to type in a value using the Query$
function, which has OK and Cancel buttons. If the user chooses OK, the macro
attempts to call a nonexistent macro named  notthere in line 5. This causes a
jump to the error routine in line 10. If the user chooses cancel in the Query$
function, the program jumps to the cancel routine in line 7.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Query$



ΓòÉΓòÉΓòÉ 692. Using the ONERROR statement ΓòÉΓòÉΓòÉ

A macro runtime error can occur in several circumstances, including calling a
macro that cannot be found, or passing a non-numeric string to a function that
requires a number. If this happens, the macro program normally terminates with
an error message that identifies the cause of the error. By using the ONERROR
statement, you can direct program control to an error handling routine that
could inform the user of the error, and suggest corrective action and/or
perform a cleanup.


Another important function of the ONERROR statement is to allow the macro to
clean up after itself. This is particularly important if the macro uses Global
Variable Functions or ASCII File Macro Functions. Exiting a macro without
clearing these routines could affect the later operation of Ami Pro and OS/2.

If the macro encounters an error condition, Ami Pro looks for an ONERROR
statement in the currently running macro function. If Ami Pro finds no ONERROR,
it searches succeeding parent functions for an ONERROR statement, until it
encounters the main function. This means that each macro function can have its
own error processing.

If an error occurs in a subroutine and the macro processes it in that routine,
Ami Pro does not search any farther for other ONERROR statements. You should
ensure that parent functions correctly handle error conditions.

When using the ONERROR and ONCANCEL statements, make sure that they are at the
beginning of the macro. If an error occurs before these statements, control may
not transfer to the error or cancellation routines.

Syntax
ONERROR Label
Label is the name of a label to which you should transfer control in case of
error.

Example
The following is an example of the ONERROR and ONCANCEL statements:
 FUNCTION main()
 ONERROR ErrorRoutine 'set error routine
 ONCANCEL CancelRoutine 'set cancel routine
 Query$ ("Choose OK or CANCEL.") ' set up routine
 CALL notthere() ' this causes an error, since macro not there
 GOTO endit
 CancelRoutine:
 message ("You canceled the macro.")
 GOTO endit
 ErrorRoutine:
 message ("There has been a macro error.")
 endit:
 END FUNCTION

This macro defines program locations for error and cancel handling in lines 2
and 3. It then asks the macro user to type in a value using the Query$
function, which has OK and Cancel buttons. If the user chooses OK, the macro
attempts to call a nonexistent macro named  notthere in line 5. This causes a
jump to the error routine in line 10. If the user chooses cancel in the Query$
function, the program jumps to the cancel routine in line 7.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Using the ONCANCEL Statement





ΓòÉΓòÉΓòÉ 693. Using the SWITCH and CASE statements ΓòÉΓòÉΓòÉ

In a macro function, the lines of code are usually executed in the order they
appear. You can divert the flow of execution through unconditional branching. A
SWITCH statement behaves like multiple IF statements for one variable.
Depending on the value of the variable, control can be transferred to different
sections of the macro.


The SWITCH and CASE statements work together to execute a series of program
steps based on the value of a single variable. These statements are similar to
the IF/ELSEIF statements. The major difference is that while you can execute
different statements based on the values of different variables using the IF
statement (IF a = 1 then ... ELSEIF b = 2 ... ELSEIF c = 3 ... ), all of the
statements executed with a CASE statement depend on the variable defined in the
SWITCH statement.

When the macro encounters the SWITCH statement, the value of Variable is
stored. This value is then compared to the expression in the first CASE
statement. If they are equal, the statements between that CASE statement and
the next CASE statement, the DEFAULT statement, or the ENDSWITCH statement,
whichever comes first, is executed. Control then passes to the first statement
beyond the ENDSWITCH statement. If the variable and the CASE expression are not
equal, the statements are not executed. The program continues to the next CASE
statement, which is evaluated in the same way.

If none of the CASE expressions matched the variable by the time the DEFAULT
statement is encountered, the statements between the DEFAULT and ENDSWITCH
statements are executed. If there is no DEFAULT statement, control passes to
the first statement beyond the ENDSWITCH statement.

Syntax
SWITCH Variable
   CASE Expression1
      Statements1
   [CASE Expression2
      Statements2...]
   [DEFAULT
      Statements3]
ENDSWITCH
Variable is a defined variable name that is compared to the expressions in the
CASE statements.
Expression1 is an expression that is compared to Variable.
Statements1 are program statements that are executed if Variable is equal to
Expression1.
Expression2 is an expression that is compared to Variable.
Statements2 are program statements that are executed if Variable is equal to
Expression2.
Statements3 are program statements that are executed if none of the expressions
in any CASE statement is equal to Variable.

Example
The following example counts the frequency of occurrence of four words in a
document and reports the percentage of each word used:
 FUNCTION wordfreq()
 word1 = Query$ ("Type the first word:")
 word2 = Query$ ("Type the second word:")
 word3 = Query$ ("Type the third word:")
 word4 = Query$ ("Type the fourth word:")
 DraftMode()' put in DraftMode
 TYPE ("[ctrlhome]") ' go to top of file
 w1cnt = 0 ' initialize counters
 w2cnt = 0
 w3cnt = 0
 w4cnt = 0
 ocnt = 0
 loop: 'loop point for each word
 word = CurWord$()  ' get word contents
 SWITCH word
    CASE (word1) ' if a match
       w1cnt = w1cnt + 1 ' bump word count
    CASE (word2)
       w2cnt = w2cnt + 1
    CASE (word3)
       w3cnt = w3cnt + 1
    CASE (word4)
       w4cnt = w4cnt +1
    default
       ocnt = ocnt +1 ' didn't match our words
 ENDSWITCH
 TYPE ("[ctrlright]") ' to next word
 IF (0 = AtEOF()) ' at the end of the file yet ?
    GOTO loop ' no; continue
 ENDIF
 totcount = w1cnt + w2cnt + w3cnt + w4cnt + ocnt
 p1 = (w1cnt / totcount) * 100
 p1 = FormatNum$ ("", "", 2, p1)
 p2 = (w2cnt / totcount) * 100
 p2 = FormatNum$ ("", "", 2, p2)
 p3 = (w3cnt / totcount) * 100
 p3 = FormatNum$ ("", "", 2, p3)
 p4 = (w4cnt / totcount) * 100
 p4 = FormatNum$ ("", "", 2, p4)
 message ("There are {w1cnt} cases of {word1}, or {p1}%")
 message ("There are {w2cnt} cases of {word2}, or {p2}%")
 message ("There are {w3cnt} cases of {word3}, or {p3}%")
 message ("There are {w4cnt} cases of {word4}, or {p4}%")
 message ("Total words in document: {totcount}")
 END FUNCTION

Lines 2 - 5 of this macro ask the macro user for the four words to be counted
using the Query$ function and assign values to the variables word1 to word4.
Line 6 uses the macro function DraftMode to put Ami Pro in Draft Mode, which
speeds up processing of the macro. Lines 8 through 12 define the variables used
for counters and initializes them to 0. After these setup statements, the body
of the macro loop begins with the macro function getword in line 14, which gets
the current word in the document, and places its value in the variable word.

Line 15 of the macro is the SWITCH statement. It sets the value of the variable
the following CASE statements use to compare to the value of word. The CASE
statement in line 16 compares the value of word to word1, the first word whose
frequency we are trying to count. If there is a match, then the counter for the
first word is incremented, and control jumps to line 27 following the ENDSWITCH
statement. If not, control passes to the following line where the value of word
is compared to the second word we are counting, and so forth. If a match is not
found by line 24, the default case, the program increments the counter of
other, non-matched words in the document. The ENDSWITCH statement in line 26
indicates the end of the SWITCH statement.

Line 27 advances the insertion point to the next word and lines 28 - 30 jump
back to line 13. The process is repeated for the following word in the file
until the entire file has been examined. Line 31 adds the count of each word
type together to determine the total number of words in the document. Lines 32
- 39 calculate the average usage for each of the words, and use the FormatNum$
macro function to format the numbers as percentages. Finally, lines 40 - 44
display the result of the word frequency count to the user.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Using the IF/THEN Statements


ΓòÉΓòÉΓòÉ 694. Using the WHILE statement ΓòÉΓòÉΓòÉ

Looping allows repetitive tasks to be coded once and executed repeatedly until
a certain condition becomes true or until an event occurs. The WHILE/END
structure executes the lines of code between WHILE and WEND as long as a
certain expression evaluates true. As soon as that expression evaluates false,
control transfers to the first line of code after WEND.


The WHILE statement is useful if you want to ensure that some condition has
been fulfilled before continuing with other steps in the macro.

When the WHILE statement is encountered in a macro program, the condition
specified in condition is evaluated. If the condition evaluates to TRUE, then
the statements between the WHILE and WEND statements are executed. If the
condition is false, macro execution continues beyond the WEND statement.
Following execution of the statements, the program goes back to the WHILE
statement and reevaluates the condition. As long as the condition remains TRUE,
the statements through the WEND statement continue to be executed.

The statements between a WHILE/WEND loop are not executed at all if the
condition specified in the WHILE statement is FALSE when first evaluated. It is
also possible to create an infinite loop in a WHILE/WEND loop if the statements
between them do not affect the condition in the WHILE statement.

Syntax
WHILE (Condition)
   Statements
WEND
Condition is a condition that evaluates to either TRUE or FALSE.
Statements are macro program statements.

Example
The following example illustrates using the WHILE loop in a macro to count the
number of characters.
 FUNCTION wc()
 DraftMode() ' ensure we are in DraftMode
 TYPE ("[ctrlhome]") ' go to top of file
 counter = 0 ' initialize counter
 WHILE (NOT(AtEOF())) ' as long as not at end of file
    counter = counter +1
    TYPE ("[right]") ' ahead a character
 WEND
 message ("There are {counter} characters in the file.")
 END FUNCTION

Line 2 of this macro changes Ami Pro to Draft Mode for faster operation, line 3
positions the insertion point at the beginning of the file, and line 4
initializes the counter variable to 0. Line 5, the WHILE statement, tells the
macro to execute the following statements as long as the insertion point is not
at the end of the file. Lines 6 and 7 form the loop of the WHILE statement,
incrementing the counter and advancing to the next word in the file. The WEND
statement in line 8 tells the macro to go to the WHILE statement and repeat the
loop. Line 9 displays the character count to the user, and line 10 ends the
macro.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements





ΓòÉΓòÉΓòÉ 695. Using Variables ΓòÉΓòÉΓòÉ

Variables are named place holders that can be assigned values. The values of a
variable can be changed while the macro is running.


Before you can use a variable, you must define it. By defining it, you tell the
macro that the variable exists. While you must formally dimension array
variables, you can formally or implicitly declare single element variables. The
limit for string variables is 498 characters.

You can use both local single element variables and array variables in macro
programs, but only in the macro that creates them. The macro language provides
functions that allow for creation and maintenance of global variables that any
macro can use during an Ami Pro session.

In Ami Pro, you can access global variables by name or by number. Ami Pro does
not have different variable types, such as integers, floating point numbers,
and characters. Ami Pro stores each variable as a string and converts the
string to the appropriate numeric type when running the macro.

When you reference a variable in an arithmetic expression, Ami Pro converts it
to integer or floating point format and then processes it. Because Ami Pro does
not evaluate variable contents until needed, variables that do not contain
numbers cause run-time errors if you use them in arithmetic expressions.

You can pass the address of a variable or array to a routine. This allows a
subroutine to modify the calling routineТs variable. This is useful when a
subroutine needs to "return" more than one value. For example, to pass its
address use the "&" directly before the variable:
passvar(&myvar)

This would pass the address of the variable myvar to subroutine passvar.
Passvar does not declare this variable in any special way; however, to access
it, the reference needs to have an "*" before the variable. The asterisk (*)
and the ampersand (&) denote indirection.

Example
 FUNCTION passvar(pv)
 *pv=*pv+1
 END FUNCTION

Here, passvar increments the caller's variable by one.

To allow for variable indirection, use a semicolon to denote an end of
statement. It is optional except when you use indirection.

See also:

    Ami Pro Macro Language Contents
    Array Macro Functions
    Declaring Formal Variables Using the DEFSTR Statement
    Declaring Formal Variables Using the DIM Statement
    Declaring Variables Implicitly
    Identifying Strings as Variables
    String Macro Functions
    Understanding the Lifetime and Visibility of a Variable
    Using Global Variables to Hold Values


ΓòÉΓòÉΓòÉ 696. Declaring Formal Variables Using the DEFSTR Statement ΓòÉΓòÉΓòÉ

You can formally declare single element variables using the DEFSTR statement
and array variables using the DIM statement. The most common use for DEFSTR is
to declare a variable for use with indirection (&).


The DIM statement does the same thing that the DEFSTR statement does, except
that it defines an array variable, rather than a single element variable. It
includes an expression that allows you to declare the number of elements in the
array. Ami Pro evaluates the DIM statement each time and updates the contents
of the array.

Syntax
DEFSTR Name1[, Name2]...
Name1 and Name2 are the names of the variables you wish to define.

Example
The following example illustrates the use of the DEFSTR statement:
 FUNCTION typeami()
 DEFSTR progname
 progname = "Ami Pro"
 TYPE ("The name of this program is {progname}.")
 END FUNCTION

In this example, progname is a single element variable in line 2. Line 3
assigns progname the value "Ami Pro", and in the fourth line, the TYPE function
types a message to the screen with the variable name and other text.

See also:

    Ami Pro Macro Language Contents
    Array Macro Functions
    Using Variables
    Declaring Formal Variables Using the DIM Statement
    Declaring Variables Implicitly
    Identifying Strings as Variables
    Understanding the Lifetime and Visibility of a Variable
    Using Global Variables to Hold Values



ΓòÉΓòÉΓòÉ 697. Declaring Formal Variables Using the DIM statement ΓòÉΓòÉΓòÉ

You can formally declare single element variables using the DEFSTR statement
and array variables using the DIM statement. The most common use for DEFSTR is
to declare a variable for use with indirection (&).


The DIM statement does the same thing that the DEFSTR statement does, except
that it defines an array variable, rather than a single element variable. It
includes an expression that allows you to declare the number of elements in the
array. Ami Pro evaluates the DIM statement each time and updates the contents
of the array.

Syntex
DIM array1 (count1)[ array2 (count2)]...
Array1 and array2 are the names of the arrays to be dimensioned.
Count1 is the maximum number of elements in array1.
Count2 is the maximum number of elements in array2.

Example
The following example illustrates the use of the DIM statement to define an
array:
 FUNCTION typenames()
 DIM names(4)
 names(1) = "Cassie Conners"
 names(2) = "David Zane"
 names(3) = "Cris Walker"
 names(4) = "Peyton Myers"
 FOR count = 1 to 4
   curname = names(count)
   TYPE ("Name number {count} is {curname}.[ENTER]")
 NEXT
 END FUNCTION

Line 2 of this macro declares that there are four elements in the array names.
Lines 3 Ч 6 assign each element of the array a string value. Line 7 sets up a
FOR/NEXT loop with four iterations. Line 8 assigns the value of the current
element in the names array to the variable curname. Then, line 9 types the text
into the current file, followed by the ENTER key, which ends the paragraph.
Lines 10 and 11 end the FOR loop and the macro.

See also:

    Ami Pro Macro Language Contents
    Array Macro Functions
    Using Variables
    Declaring Formal Variables Using the DEFSTR Statement
    Declaring Variables Implicitly
    Identifying Strings as Variables
    String Macro Functions
    Understanding the Lifetime and Visibility of a Variable
    Using Global Variables to Hold Values


ΓòÉΓòÉΓòÉ 698. Declaring Variables Implicitly ΓòÉΓòÉΓòÉ

You do not have to declare single element variables formally. You can
implicitly declare a single element variable by assigning it a value within the
macro. You cannot implicitly dimension array variables. The only way to tell
the macro program how many elements to expect in the array is to dimension it.


Example
 FUNCTION main ()
 your name = Query $ ("What is your name?")
 Message ("Your name is {your name}.")
 END FUNCTION

This macro implicitly declares the single element variable, your name, on Line
2. Line 3 displays a dialog box with the variable your name.

See also:

    Ami Pro Macro Language Contents
    Array Macro Functions
    Using Variables
    Declaring Formal Variables Using the DEFSTR Statement
    Declaring Formal Variables Using the DIM Statement
    Identifying Strings as Variables
    Understanding the Lifetime and Visibility of a Variable
    Using Global Variables to Hold Values




ΓòÉΓòÉΓòÉ 699. Identifying Strings as Variables ΓòÉΓòÉΓòÉ

Many macro functions accept strings as their arguments. You can incorporate
single element variables into strings by surrounding them with curly braces ({
}). Consider the following line of macro code:

TYPE ("The first item on the list is {item}")

In this example, the macro knows when to type the word 'item' and when to use
the variable referenced by the name 'item'. By placing curly braces around the
variable name when you use it as part of a string, you use the contents of the
variable rather than its name.

You can also use curly braces around a single element variable name at any time
to improve the clarity of the macro. Using curly braces around variable names
indicates that the word inside the braces is a variable name rather than
something else.

You cannot use curly braces around array variables.

See also:

    Ami Pro Macro Language Contents
    Array Macro Functions
    Using Variables
    Declaring Formal Variables Using the DEFSTR Statement
    Declaring Formal Variables Using the DIM Statement
    Declaring Variables Implicitly
    String Macro Functions
    Understanding the Lifetime and Visibility of a Variable
    Using Global Variables to Hold Values




ΓòÉΓòÉΓòÉ 700. Understanding the lifetime and visibility of a variable ΓòÉΓòÉΓòÉ

The lifetime of a variable refers to the time that the variable maintains its
value. This is usually as long as the macro function is running. The exception
is the global variable, which retains its value during the entire Ami Pro
session.


The visibility of a variable refers to macro functions that recognize the
variable.

Within Ami Pro, each variable is visible only to the macro that defined it and
lasts only for the duration of that macro. This means that if one macro calls
another macro as a function, the variables in the calling macro are not
available to, and cannot be modified by, the called macro. In addition, if a
macro finishes running with certain values stored in variables, running the
macro a second time reinitializes the variables and loses previously existing
values.

When one macro calls another macro as a function, it can pass arguments to the
called macro, which are usually variables from the parent macro. When this
happens, Ami Pro makes a copy of each variable and passes the copy to the
function. Since the function only receives a copy of the original, the function
cannot modify the original variable. The function can return a value to the
calling macro, and you can assign that value to a variable within the calling
macro.

Example
The following example illustrates passing variables to functions:
 FUNCTION main()
 var1 = "original value, main macro"
 TYPE ("{var1}[ENTER]")
 CALL upcase (var1)
 TYPE ("{var1}[ENTER]")
 var1 = CALL upcase (var1)
 TYPE ("{var1}[ENTER]")
 END FUNCTION

 FUNCTION upcase( var2)
 TYPE("original value, upcase macro[ENTER]")
 var3 = UCASE$( var2)
 TYPE ("{ var2}[ENTER]")
 upcase =  var3
 END FUNCTION

The output from the above macro is as follows:
1  original value, main macro
2  original value, upcase macro
3  original value, main macro
4  original value, main macro
5  original value, upcase macro
6  original value, main macro
 7  ORIGINAL VALUE, MAIN MACRO

The first line of output comes from line 3 of the main macro, and displays the
original value of var1 as defined in the main macro. Line 3 of the output comes
from line 13 of the upcase macro. Even though var2 passes as an argument to the
UCASE$ function (which uppercases the argument), its value has not changed.
Line 4 of the output is from line 5 of the main macro, and illustrates again
that passing an argument to another macro does not affect the value of that
argument once it has returned to the main macro.

Lines 5 and 6 of the output show another iteration of the upcase macro, and
have the same results as occurred the first time through. Line 7 of the output
is from line 7 of the main macro, and shows that the var1 string from the main
macro became uppercase when assigned the result of the upcase macro in line 6.

See also:

    Ami Pro Macro Language Contents
    Using Variables
    Declaring Formal Variables Using the DEFSTR Statement
    Declaring Formal Variables Using the DIM Statement
    Declaring Variables Implicitly
    Identifying Strings as Variables
    Using Global Variables to Hold Values




ΓòÉΓòÉΓòÉ 701. Using global variables to hold values ΓòÉΓòÉΓòÉ

Global variables are like safety deposit boxes that you can use to store
information when it is not in use. When a macro needs to store information for
later use, it creates a global variable and assigns the value of the program
variable to the global variable. Later, another macro, or another instance of
the same macro, can retrieve the value of the global variable, assign it to a
variable name in the macro, and use or change it as needed.


See also:

    Ami Pro Macro Language Contents
    Using Variables
    Declaring Formal Variables Using the DEFSTR Statement
    Declaring Formal Variables Using the DIM Statement
    Declaring Variables Implicitly
    Identifying Strings as Variables
    Understanding the Lifetime and Visibility of a Variable




ΓòÉΓòÉΓòÉ 702. Using Numbers, Strings, and Operators ΓòÉΓòÉΓòÉ

An expression is a combination of numbers, strings, variables, and operators
used to determine a result. You can assign the result to a variable, use it as
an argument to a function or macro, return it as the result of a macro, or use
it to determine whether or not to execute a macro routine.


Examples
Some examples of expressions are:
 var
 var + var1
 var1 | var2
 var * 3 >var2
 var < 10 AND var >0

In line 1, the expression is a single element variable. If you do not use
operators in the expression, the result of the expression is the variable or
constant. In line 2, the expression uses the mathematical operator + to add two
variables together. Line 3 uses the bitwise OR operator | to "OR" the bit
values of var1 and var2. Line 4 uses the relational operator > to compare two
values. Line 5 uses the logical operator AND to compare two logical values to
determine the result.

Operators are either mathematical, relational, or logical, and operate on the
other elements of the expression to determine the result.

The four types of operators are Mathematical Operators, Bitwise Operators,
Relational Operators, and Relational Operators.

See also:

    Ami Pro Macro Language Contents
    Understanding Operator Precedence
    Using Mathematical Operators
    Using Bitwise Operators
    Using Relational Operators
    Using Logical Operators


ΓòÉΓòÉΓòÉ 703. Understanding operator precedence ΓòÉΓòÉΓòÉ

Ami Pro evaluates expressions with multiple operators by first performing
operations with a higher precedence, followed by operations with a lower
precedence. If two operations have the same precedence, Ami Pro evaluates from
left to right.


The precedence of operators is:
    NOT
    Multiplication and Division
    Addition and Subtraction
    Bitwise AND and Bitwise OR
    Greater Than, Less Than, Greater Than or Equal To, Less Than or Equal To
    Equal To and Not Equal To
    AND and OR

You can use parentheses to determine the order of expression evaluation. If you
use parentheses, Ami Pro first evaluates expressions inside the innermost set
of parentheses, followed by the next set of parentheses, etc.

If you use two operators in a row, you must separate the operators by
parentheses.

Example
The following examples illustrate expression evaluation. Some of the examples
use parentheses to change the evaluation order.
var > var1    'is true if var > var1
var = 4       'is true if var = 4
name < "Jones"       'is true if name is anything besides Jones
var + var1 <= var2 * var3
var > var1 AND var1 < 10
var <>0 OR (NOT IsNumeric(var))    'two operands in a row
(c >= "A" AND c <= "Z") OR (c >= "a" AND c <= "z")
'determines if the variable c is alphabetic
var = 0 AND (IsNumeric(var1) OR IsNumeric (var2)) OR var3 >0
' true if var3 >0 or if var = 0 and either var1 or var2 is numeric
var = 0 AND ((IsNumeric(var1) OR IsNumeric (var2)) OR var3 >0)
' true if var = 0 and either var1 or var2 is numeric or var3 >0

See also:

    Ami Pro Macro Language Contents
    Using Numbers, Strings, and Operators
    Using Mathematical Operators
    Using Bitwise Operators
    Using Relational Operators
    Using Logical Operators


ΓòÉΓòÉΓòÉ 704. Using mathematical operators ΓòÉΓòÉΓòÉ

Mathematical operators include addition, subtraction, multiplication, and
division.


The mathematical operators are:
    Name (Character) - Definition
    Multiplication (*) - Multiplies the value to the left of the operator by
    the value to the right of the operator.
    Division (/) - Divides the value to the left of the operator by the value
    to the right of the operator.
    Addition (+) - Adds the value to the left of the operator to the value to
    the right of the operator.
    Subtraction (-) - Subtracts the value to the right of the operator from the
    value to the left of the operator.

Values used by mathematical operators must be numeric, otherwise a runtime
macro error can result.

See also:

    Ami Pro Macro Language Contents
    Using Numbers, Strings, and Operators
    Understanding Operator Precedence
    Using Bitwise Operators
    Using Relational Operators
    Using Logical Operators




ΓòÉΓòÉΓòÉ 705. Using bitwise operators ΓòÉΓòÉΓòÉ

Bitwise operators include the bitwise AND and the bitwise OR.


The bitwise operators are:
    Name (Character) - Definition
    Bitwise AND (&) - Performs a logical AND between each bit of the value to
    the left of the operator and the value to the right of the operator.
    Bitwise OR (|) - Performs a logical OR between each bit of the value to the
    left of the operator, and the value to the right of the operator.

Values used by bitwise operators must be integers or a runtime macro error can
result. Bitwise operators, which compare each bit of a value, are not the same
as logical operators, which compare the entire value.

See also:

    Ami Pro Macro Language Contents
    Using Numbers, Strings, and Operators
    Understanding Operator Precedence
    Using Mathematical Operators
    Using Relational Operators
    Using Logical Operators


ΓòÉΓòÉΓòÉ 706. Using relational operators ΓòÉΓòÉΓòÉ

Relational operators include equality, greater than, less than, greater than or
equal to, less than or equal to, or not equal to.


The relational operators are:
    Name (Character) - Definition
    Equals (=) - Compares the value to the left of the operand and the value to
    the right of the operand. The result of the comparison is TRUE if the
    values are equal.
    Greater Than (>) - Compares the value to the left of the operand and the
    value to the right of the operand. The result is TRUE if the value to the
    left is greater than the value to the right.
    Less Than (<) - Compares the value to the left of the operand and the value
    to the right of the operand. The result is TRUE if the value to the left is
    less than the value to the right.
    Greater Than or Equal To (>=) - Compares the value to the left of the
    operand and the value to the right of the operand. The result is TRUE if
    the value to the left is greater than or equal to the value to the right.
    Less Than or Equal To (<=) - Compares the value to the left of the operand
    and the value to the right of the operand. The result is TRUE if the value
    to the left is less than or equal to the value to the right.
    Not Equal To (<> or !=) - Compares the value to the left of the operand and
    the value to the right of the operand. The result is TRUE if the value to
    the left is not equal to the value to the right.

Values used by relational operators can be strings, numbers, or expressions.

See also:

    Ami Pro Macro Language Contents
    Using Numbers, Strings, and Operators
    Understanding Operator Precedence
    Using Mathematical Operators
    Using Bitwise Operators
    Using Logical Operators




ΓòÉΓòÉΓòÉ 707. Using logical operators ΓòÉΓòÉΓòÉ

Logical operators are:

    Logical And (AND) - Logically compares the value to the left of the operand
    with the value to the right of the operand. The result is TRUE if both
    expressions evaluate to TRUE.
    Logical Or (OR) - Logically compares the value to the left of the operand
    with the value to the right of the operand. The result is TRUE if either
    expression evaluates to TRUE.
    Logical Not (NOT) - Evaluates the value to the right of the operand. The
    result is TRUE if the expression evaluates to FALSE. The result is FALSE if
    the expression evaluates to TRUE.

Values used by logical operators can be integers, numbers, strings or
expressions. If the value is equal to 0 or to the null string (""), it is
FALSE. If it is anything else, it is TRUE.

See also:

    Ami Pro Macro Language Contents
    Using Numbers, Strings, and Operators
    Understanding Operator Precedence
    Using Mathematical Operators
    Using Bitwise Operators
    Using Relational Operators


ΓòÉΓòÉΓòÉ 708. Using Constants ΓòÉΓòÉΓòÉ

A constant expression is an expression whose value does not change for the
duration of the macro program. Normally, constants are strings of text that the
macro uses.


There are two types of constants: defined and predefined. You create defined
constants in your macro. Ami Pro provides predefined constants you may use in
your macro.

See also:

    Ami Pro Macro Language Contents
    Defining Constants
    Predefining Constants




ΓòÉΓòÉΓòÉ 709. Defining constants ΓòÉΓòÉΓòÉ

A constant expression is normally a string of text in a macro. There are
several characters that you need to represent in a special manner so that Ami
Pro can recognize them within strings. These characters are the left curly
brace ({), the left square brace ([), and the double quotation mark (").


Because curly braces surround variable names in strings, you must type two
curly braces to type a curly brace within a string. Use the TYPE function to
represent key names in strings. Since square braces surround a key name, you
must type two square braces to represent a square brace within a string.

Double quotation marks surround strings to define their boundaries. To type a
double quotation mark within a string, you must type two quotation marks in a
row. You do not need to type two right curly braces or two right square braces
when you are using them in strings.

Example
The following example illustrates the representation of strings within a macro:
 FUNCTION strings()
 'a string assigned to a variable
 var = "Variable"
 'a typical string
 TYPE ("This is a constant string of text. ")
 'a string with a key name
 TYPE ("This string has a key name inside it.[ENTER]")
 'a string with a variable name
 TYPE ("This string contains a variable with the value {var}. ")
 'a string with curly braces embedded
 TYPE ("The curly brace character, {{, is used to fence a variable. ")
 'a string with a square brace character
 TYPE ("The square brace character, [[, is used to fence a key name. ")
 'a string with embedded quotes
 TYPE ("Use quotation marks like this ""string"" to define a string.")
 END FUNCTION

The output of the macro looks like the following:
This is a constant string of text. This string has a key name inside it.

This string contains a variable with the value Variable. The curly brace
character, {, fences a variable. The square brace character, [, fences a key
name. Use quotation marks like this "string" to define a string.

See also:

    Ami Pro Macro Language Contents
    Using Constants
    Predefining Constants


ΓòÉΓòÉΓòÉ 710. Predefining constants ΓòÉΓòÉΓòÉ

To make a macro more readable, you can use constants to represent values that
do not change in a macro. Ami Pro uses a list of defined constants to perform
substitutions when they are used in a macro. This list is most useful when
using Ami Pro functions that require numeric arguments be given to them for
interpretation. When the macro is compiled, the compiler substitutes the
constant in the macro for the number in the list of defined constants, unless
the name is inside a string.


Many functions use flags as parameters to the function. A flag is a number that
conveys a meaning to the function. By adding numbers together, a number can
extract several different values when the macro runs.

Example
The following is an example of using predefined constants in a macro:
 FUNCTION lineson()
 flag = NumberLines+NumberEveryOther+ResetEachPage
 ' compiles as flag = 1+4+16, so flag = 21
 LineNumber (flag, "Body Text")
 message ("Line Numbering On")
 END FUNCTION

 FUNCTION linesoff()
 LineNumber (off, "Body Text")
 ' compiles as LineNumber (0,"Body Text")
 message ("Line Numbering Off")
 END FUNCTION

In this example, the two macros turn line numbering on and off in a file. The
lineson macro turns on line numbering every other line. Then it resets the
numbering to 1 on each page. The  linesoff macro turns off line numbering.

One of the parameters to the LineNumber function is a flag that specifies which
line numbering options to use. Ami Pro adds the numbers representing these
options together and passes them to the function. The option to turn the
numbering on is 1; the option to number every other line is 4, and the option
to reset numbering each page is 16. You can use predefined constants to add
these numbers and then place the total in the function call. This makes it
clear exactly what the macro is doing.

The macro uses the same procedure in the  linesoff macro. To turn numbering
off, the macro uses a flag of 0. Since off is defined as 0 in the substitution
list, this substitution makes the macro more readable.

Ami Pro stores the substitution list in a glossary file named MACDEFIN.SAM in
the Ami Pro directory (usually C:\AMIPRO). The file contains substitutions for
predefined constant names. You can add to the glossary file. The glossary item
name is the predefined constant name in the macro. Ami Pro substitutes the
predefined constant name with the item. Neither the defined name nor the
replacement can contain spaces. The defined name must begin with an alphabetic
character and can contain only letters and numbers.

If you modify this file, macros compiled under the modified MACDEFIN.SAM may
not compile on other systems. Copy the MACDEFIN.SAM to the Ami Pro directory
(usually C:\AMIPRO) to compile successfully.

See also:

    Ami Pro Macro Language Contents
    Using Constants
    Defining Constants



ΓòÉΓòÉΓòÉ 711. Calling Built-In Functions and Other Macros ΓòÉΓòÉΓòÉ

To execute a subroutine, one macro can call another macro and then return a
single value to the calling macro. Before a macro can call another macro, you
can identify it prior to its first use with the DECLARE statement. You can also
identify it with each use by using either the CALL or CALLI statement.


It does not make any difference whether you use the DECLARE statement once at
the beginning of a calling macro or you use the CALL or CALLI statement each
time in the subroutine.

When executing another macro, Ami Pro follows a search path to find the macro.
You do not have to specify a full path to the macro.

You can also call macro functions within a macro. You do not need to declare or
call built-in functions. To use a built-in function, use its name. You can call
Ami Pro functions by providing the parameters required for the function and
having the function execute. You can also call an Ami Pro function by giving
the function name without parentheses. This displays the dialog box for the
function and then allows the macro user to choose the parameters for the
function.

See also:

    Ami Pro Macro Language Contents
    Calling Built-In Functions
    Calling Ami Pro Functions
    Determining the Location of a Macro When it is Run
    Returning Values From Called Macros
    Using the CALL and CALLI Statements
    Using the DECLARE Statement



ΓòÉΓòÉΓòÉ 712. Calling built-in functions ΓòÉΓòÉΓòÉ

The Ami Pro macro language offers a variety of functions you can call from
within a macro. The macro language includes functions to control the execution
of the macro, to allow interaction with the user, to allow interaction with the
Ami Pro program itself, and to allow interaction with other programs using
Dynamic Data Exchange (DDE) protocol.


Syntax
[Result = ]Function([Parm1][[,] [Parm2...])
Result is a variable that receives the return value of the function.
Function is the name of the function you want to use.
Parm1 and parm2 are the parameters required by the function, if any.

Example
The following macro uses the built-in functions GetDocPath$, SetDocPath, Decide
and Query$ to get the user's default document path, display it, and to allow it
to be changed:
 FUNCTION changepath()
 path = GetDocPath$()       ' gets current path
 response = Decide ("Change Document Path From {path}?")
 IF (response)       ' user said yes to dialog box
    path = Query$ ("Type New Path:")
    SetDocPath (path)
 ENDIF
 END FUNCTION

Line 2 of the macro uses the GetDocPath$ function to get the current path. This
line stores the result of this function in the variable path. Line 3 of the
macro uses the Decide function to display a dialog box and ask the user if he
wants to change his path. The Decide function requires one parameter, the
prompt you should use in the dialog box. It returns either TRUE or FALSE,
depending on whether the user chose Yes or No in the dialog box. This line
assigns the return value from the Decide function to the variable response. If
the user decided to change the path, the Query$ function in line 5 displays an
edit box for the user to type the new path. This line returns the typed value
and assigns it to the variable path. Finally, line 6 sets the new document path
using the SetDocPath function.

See also:

    Ami Pro Macro Language Contents
    Calling Built-In Functions and Other Macros
    Calling Ami Pro Functions
    Determining the Location of a Macro When it is Run
    Returning Values From Called Macros



ΓòÉΓòÉΓòÉ 713. Calling Ami Pro functions ΓòÉΓòÉΓòÉ

You can execute almost any Ami Pro function using a macro. You can access Ami
Pro functions through pulldown menus that have equivalent functions in the
macro language.


When using an Ami Pro function, the macro can provide all the functions the
program requires, which causes the function to automatically execute. The macro
can also start the function and allow the user to make choices for that
function in the dialog box.

Syntax
[Result = ]Function([Parm1][[,] [Parm2...])
Result is a variable that receives the return value of the function.
Parm1 and Parm2 are the parameters required by the function, if any.

The syntax for calling an Ami Pro function that prompts the user for parameters
is:
[Result = ] Function
Function is the name of the function you want to use.

Return Value
1 (TRUE) if the function completes successfully.
0 (FALSE) if the user canceled the function.
-2 (GENERALFAILURE) if the state of the program prohibited the function at the
time or the function could not complete for some other reason.

Example
The following macro sets the line spacing in the current document to single
spacing:
 FUNCTION singlespace()
 result = Spacing(SpaceSingle)
 IF (result <> TRUE) ' the spacing was not equal to single
    message ("Failed to set single spacing.")
 ENDIF
 END FUNCTION

In line 2, the Ami Pro function Spacing is called. The Spacing function takes a
single argument, with the desired spacing. SpaceSingle is defined to -1, which
is the correct value for single spacing. The result of the function is returned
to the variable result. This variable is examined in line 4, and if the spacing
change did not occur, an error message is displayed for the user.

The following macro sets line spacing but allows the user to determine the
desired spacing:
 FUNCTION setspace()
 result = Spacing
 IF (result = false)
    message ("Did not set spacing")
 ENDIF
 END FUNCTION

In line 2, the macro calls the Spacing function without any parentheses. This
causes the Line Spacing dialog box to display on the screen so the user can set
the spacing. As in the previous example, this line assigned the result of the
function call to the variable so that a message can display if the spacing did
not change.

See also:

    Ami Pro Macro Language Contents
    Calling Built-In Functions and Other Macros
    Calling Built-In Functions
    Determining the Location of a Macro When it is Run
    Returning Values From Called Macros


ΓòÉΓòÉΓòÉ 714. Determining the location of a macro when it is run ΓòÉΓòÉΓòÉ

Ami Pro uses a search path to find the location of the macros to execute. If a
macro contains a full path specification, Ami Pro looks there. If there is no
path specified, Ami Pro searches first the default macro directory, second the
default document directory, and third the directory where Ami Pro stores
program files (usually C:\AMIPRO). If Ami Pro can not find the macro in any of
these locations, Ami Pro displays an error message.


In an Ami Pro installation the default macro path is a subdirectory of the
AMIPRO directory (usually C:\AMIPRO\MACROS). This directory may contain several
example macros. Whenever the macros dialog box displays, it defaults to
displaying macros in that directory. You can change this path by modifying the
path in User Setup Paths, by editing the amiuser3.ini file, or by using the
macro functions GetProfileString$ and WriteProfileString.

If you write macros that other people may use, you may not know the final
location of the macro file. If the macro calls another macro, assigns a macro
to a menu to call later, or uses an external dialog box, then you may not be
able to specify the path to the desired file. The macro search path allows you
to specify only the file name and macro name and allows Ami Pro to find the
macro file.

Ami Pro does not use this search path when looking for an external dialog box,
a dynamic link library (DLL), or other supporting files. If these supporting
files are in the same directory as the macro that needs them, you can use the
GetMacPath$ function to determine the default macro path. You can then use that
path to locate the supporting macro files. To determine the name of the macro
that is running, use the macro function, GetRunningMacroFile$.

See also:

    Ami Pro Macro Language Contents
    Calling Built-In Functions and Other Macros
    Calling Built-In Functions
    Calling Ami Pro Functions
    Returning Values From Called Macros
    GetMacPath$
    GetProfileString$
    GetRunningMacroFile$
    WriteProfileString



ΓòÉΓòÉΓòÉ 715. Returning values from called macros ΓòÉΓòÉΓòÉ

A called macro can return a value to the calling macro. The returned value can
be a number or a string or it can be a status code to indicate the macro
successfully completed.


You should assign the value to return to the calling macro to a variable name
with the same name as the called macro. When the called macro ends at the END
FUNCTION or EXIT FUNCTION statement, the value of the variable with the same
name as the called macro returns to the calling macro.

If you need to have more than one value returned from a called function, use
indirection (&). It passes the memory address of a variable to the called
function. The called function may then directly modify the variable. When the
called macro finishes, any modifications to the variable are reflected. You can
pass any number of variables in this manner.

Syntax
Return(Value)

Example
The following is an example of returning a value from a called macro to the
calling macro:
 FUNCTION calc()
 'this macro gets two numbers from the user, adds them together and displays
the result.
 num1 = Query$ ("Type the first number:")
 num2 = Query$ ("Type the second number:")
 result = CALL addit (num1, num2)
 result2 = CALL subtractit (num1, num2)
 message ("The sum of {num1} and {num2} is {result}.")
 message("The difference between {num1} and {num2} is {result2}.")
 END FUNCTION

 FUNCTION addit(num1, num2)
 addit = num1 + num2
 END FUNCTION

 FUNCTION subtractit(num1, num2)
 Difference = num1 - num2
 RETURN(Difference)
 END FUNCTION

In lines 3 and 4, the  calc macro uses the Query$ function to get the two
numbers from the user. It then calls the  addit macro in line 5, and stores the
return value in the variable result. Finally, the result displays in the
message function in line 7.

The  addit macro assigns the sum of the two variables to the variable addit and
then ends. By assigning the sum to the variable with the same name as the
macro, its value returns to the  calc macro.

The Subtractit macro assigns the difference of the two variables to the
variable subtractit and then ends. Its value returns to the Calc macro. By
using the RETURN statement, the macro assigns the return value to a variable
name that is different from the name of the called macro.

See also:

    Ami Pro Macro Language Contents
    Calling Built-In Functions and Other Macros
    Calling Built-In Functions
    Calling Ami Pro Functions
    Determining the Location of a Macro When it is Run
    Using the END FUNCTION Statement
    Using the EXIT FUNCTION Statement
    Query$


ΓòÉΓòÉΓòÉ 716. Integrating REXX Commands ΓòÉΓòÉΓòÉ

REXX is the OS/2 batch file programming language. You can create a REXX file
using the OS/2 Editor (E) or the OS/2 advanced Editor (EPM). All REXX command
files must have a .CMD extension for Ami Pro to recognize them. For more
information about creating REXX files, select the Information icon in the OS/2
System folder and select REXX Information.


There are several ways you can integrate REXX commands with Ami Pro:
    You can run a REXX command file directly from Ami Pro by choosing Tools
    Macros and choosing Play REXX file.
    You can call REXX command files from Ami Pro macros.
    You can use REXX commands in Ami Pro macro files.
    You can use Ami Pro macro functions in REXX command files.
    You can exchange parameters between Ami Pro macros and REXX command files.

Running REXX Command Files from Ami Pro
You can run REXX command files from Ami Pro several different ways. You can
execute a previously created REXX command file from within Ami Pro.
1.  Choose Tools Macros.
2.  Choose Play REXX File.
3.  Specify the name of the file you want to execute.
    All REXX files must have a .CMD extension for Ami Pro to recognize them.
    You can specify another drive and directory by selecting them in the list
    boxes or typing the full path in the Macro file text box.
4.  Choose OK.
    Ami Pro plays the REXX command file.

You can also create an Ami Pro macro to start a REXX command file. You can use
RexxCmd to start the command file by passing the filename any optional
arguments. The REXX file can retrieve those arguments using the ARG function.
If the REXX file includes a return statement, the return value is available in
the Ami Pro macro as the return value of RexxCmd(). For example,
stat = RexxCmd("c:\amipro\macros\myrexx.cmd", fname)
For additional information, see the REXXFIND.SMM sample macro. REXXFIND.SMM
calls the OS/2 Seek and Find routine through REXX. It then exchanges
information with the REXX function and lists the files that match the criteria.

If you want to execute a single REXX statement from an Ami Pro macro, you can
use RexxFunction which takes a REXX statement string as the parameter. If the
REXX file includes a RETURN statement, the return value is available in the Ami
Pro macro as the return value of RexxFunction. For example,
ok = RexxFunction("SysDeleteFile(""c:\test"")")
sets the variable ok to 0, but
ok = RexxFunction("return SysDeleteFile(""c:\test"")")
sets the variable ok to whatever SysDeleteFile returns.

Using Ami Pro Macro Functions in REXX Files
You can use all Ami Pro macro functions and commands in a REXX command file
invoked by Ami Pro. However, REXX does not allow a $ character in a function
name, and all Ami macro functions that return strings end with a $. To access
string functions from REXX, use the function name without the $. For example,
instead of
name = Query$("Enter your name:")
use
name = Query("Enter your name:")

You can also call an Ami Pro macro from a REXX command file invoked by Ami Pro.
For example,
x = mymacro.smm!MyMacro("myarg")
or
x = Call mymacro.smm!MyMacro("myarg")

Using Dialog Boxes with REXX
If you want to communicate with the user from a REXX command file invoked from
Ami Pro, you can write an Ami Pro macro that displays a dialog box. REXX
returns the value of the button that dismissed the box. Since Ami Pro lets you
process the contents of the dialog box interactively, you return the ID of any
control. If you want to display a message box or simply get an answer to a
question, you can also use the Ami Pro functions Message and Query (without the
$'s).

If you use the REXX functions SAY or PULL, Ami Pro intercepts these calls and
translates them to Message or Query functions. Ami Pro saves the prompt and
displays it in the query box. However, in REXX you normally prompt for a
response with SAY and immediately get the response with PULL so the message you
pass to SAY does not display until the next SAY or PULL function.

See also:

    Ami Pro Macro Language Contents
    Message$
    Query$
    REXXCmd
    REXXFunction


ΓòÉΓòÉΓòÉ 717. Transferring Program Control ΓòÉΓòÉΓòÉ

The Ami Pro macro language provides a method of transferring control to another
section of the same macro. This is useful when the macro needs to continue from
another location and it is not necessary to return to the original location. In
addition, Ami Pro provides special commands to transfer control to an error
handling routine and a user cancel handling routine.


See also:

    Ami Pro Macro Language Contents
    Using DDE Poke to access Ami Pro from another application
    Using the GOTO Statement
    Using the IF/THEN Statements
    Using Labels
    Using the ONCANCEL Statement
    Using the ONERROR Statement





ΓòÉΓòÉΓòÉ 718. Using DDE Poke to access Ami Pro from another Application ΓòÉΓòÉΓòÉ

Many OS/2 applications have macro language commands that support DDE
functionality.  Ami Pro can support these DDE commands through the use of
bookmarks. When you name an existing bookmark in a DDEPoke message, Ami Pro
replaces the contents of the bookmark with the poked data.


Generally there are three steps. First, you initiate the DDE conversation using
the other application's macro language. Usually this is done with some type of
Initiate or DDEInitiate command. Second, you use the other application's macro
language to poke data from that application into an Ami Pro bookmark. Usually
this is done with some type of Poke or DDEPoke command. Finally, you terminate
the DDE conversation using the other application's macro language. Usually this
is done with a Terminate or DDETerminate command.

Example
For example, you could write the following macro in 123 to poke data from a
spreadsheet into an Ami Pro document:
{dde-open AMIPRO;"(Untitled)"}
'Open a DDE channel to an untitled Ami Pro document
{dde-execute [MarkBookMark("DDE_BookMark1",4003)]}
'Create a bookmark in Ami Pro to poke data in to
{dde-poke Data,"DDE_BookMark1"}
'Data is the named range of information to poke into the Ami Pro bookmark
{dde-close}
'Terminate the DDE channel to Ami Pro
{Quit}

See also:

    Ami Pro Macro Language Contents
    Transferring Program Control





ΓòÉΓòÉΓòÉ 719. Using Results of Evaluations to Control a Macro ΓòÉΓòÉΓòÉ

Frequently, the value of a variable determines the next step a macro should
take. At other times, the macro should complete a series of steps a number of
times and then the program should execute other steps. The macro language
provides several statements that can control macro execution based on the value
of expressions.


The available statements include FOR/NEXT, which executes a loop a defined
number of times; IF/THEN, which executes statements only if an expression is
TRUE; the SWITCH/CASE statements, which execute a set of steps based on the
value of a variable; and the WHILE/WEND statement that repeatedly executes a
series of steps as long as an expression evaluates to TRUE.

See also:

    Ami Pro Macro Language Contents
    Using Macro Programming Statements
    Using the BREAK Statement
    Using the FOR Statement
    Using theIF/THEN Statements
    Using the SWITCH and CASE Statements
    Using the WHILE Statement



ΓòÉΓòÉΓòÉ 720. Using the Lotus Dialog Editor ΓòÉΓòÉΓòÉ

You can create a dialog box in the Dialog Editor by drawing push buttons, group
boxes, radio buttons, check boxes, text boxes, edit boxes, list boxes, combo
boxes, and static text directly onto an editing screen. After you create and
save your dialog box in the Dialog Editor, you can include it in or call it
from an Ami Pro macro.


The dialog box you create in the Dialog Editor is modal. That means the user
can make choices from the dialog box, but no other action can take place until
either OK or CANCEL has been chosen. You must include either an OK button, a
CANCEL button, or both in the dialog box to return control to the macro.

The exception to this is when you assign a callback to a particular control. If
the value of a control that has a callback assigned to it ever changes, then a
macro function specified in SetDialogCallback is instantly executed, even
though the dialog box is still displayed. This allows you to validate data
entered in a dialog box.

You can start the Dialog Editor by typing LTSDLGED at an OS/2 command prompt.
You can then choose Help Contents for more information about the Dialog Editor.

See also:

    DialogBox
    DlgClearControl
    DlgClose
    DlgEnableControl
    DlgGetListBoxCount
    DlgGetListBoxLines
    DlgHideControl
    DlgKeyInterrupt
    DlgLimitText
    DlgSetCaption
    GetDialogField$