macro
Place the specified structure editor request in the event input queue of a form component.
macro{/exit} RequestCodes
Example: macro ^RETRIEVE
Qualifiers
Qualifier | Description |
---|---|
/exit | Queues the
structure editor functions for
the current form and returns control to the previous form. Note: This switch cannot be used to execute the requests and return control when they are complete. |
Parameters
Parameter | Data Type | Description |
---|---|---|
RequestCodes | String | Text to be placed in the event input queue. If a character code or mnemonic is used, it should be preceded by a caret (^). |
Return Values
$status is set to
9
after macro ^ACCEPT
and to 10
after
macro ^QUIT
.
Value | Meaning |
---|---|
0
|
Successful |
>0 |
An error occurred. $procerror contains the exact error. |
Use
Use in Form components.
Description
The macro statement places the structure editor functions specified by RequestCodes into the event input queue. The functions are executed when the structure editor is activated. The macro statement is used primarily in menu mode.
The character codes and mnemonics that can be used with the macro statement are listed in the table:
Note: Field-level functions that navigate or insert data (such as ^NEXT_WORD, ^INS_CHAR, and so on) work only in Unifields, not in other input widgets.
Function | Numeric value | Object | Associated trigger | Purpose | Action |
---|---|---|---|---|---|
^ACCEPT | ^127^009 | Component | accept | Session control | Activate the accept trigger; intended to end edit session for current form on a positive note. (See also ^QUIT.) |
^ADD_OCC | ^127^044 | Entity | create | Data entry |
Append a new occurrence after the current
one, that is, at position When invoked by the macro statement, adds an occurrence to the first entity encountered in the form. |
^ATTRIBUTE | ^127^078 | Application | - | Text editing | Toggle the presence of the session panel and toolbar (for character attributes), if defined. |
^BEGIN_LINE | ^127^188 | Field | - | Navigation | Move the cursor to the beginning of the line. |
^BOLD | ^127^147 | Field | - | Text editing | Toggle bold character attribute. |
^BOT_OF_FORM | ^127^021 | Component | - | Navigation | Move the cursor to the form bottom. Character mode only. |
^BOTTOM | ^127^023 | Component | - | Navigation | Move the cursor to the window bottom. Character mode only. |
^CHAR | ^255^001 | Field | - | Navigation or text editing | Move cursor as ^NEXT_CHAR or ^PREV_CHAR (depending on direction mode), or apply a composite function like REMOVE to a character. |
^CLEAR | ^127^012 | Component | clear | Data entry | Activate the clear trigger (intended to clear all data from the form and hitlist without saving, or release primary key controls). |
^COMPOSE | ^127^088 | Field | - | Text editing | Activate the compose character facility |
^CURSOR_DOWN | ^127^017 | Field | - | Navigation | Move the cursor down one line. |
^CURSOR_FAST_DOWN | ^127^026 | Field | - | Navigation | Move the cursor eight lines down. |
^CURSOR_FAST_LEFT | ^127^027 | Field | - | Navigation | Move the cursor eight spaces left. |
^CURSOR_FAST_RIGHT | ^127^028 | Field | - | Navigation | Move the cursor eight spaces right. |
^CURSOR_FAST_UP | ^127^025 | Field | - | Navigation | Move the cursor eight lines up. |
^CURSOR_LEFT | ^127^018 | Field | - | Navigation | Move the cursor left one position. |
^CURSOR_RIGHT | ^127^019 | Field | - | Navigation | Move the cursor right one position. |
^CURSOR_UP | ^127^016 | Field | - | Navigation | Move the cursor up one line. |
^DETAIL | ^255^008 | Field Entity | detail | Services | Activate the detail trigger for the current field or, if the trigger is empty, the entity. |
^END_LINE | ^127^189 | Field | - | Navigation | Move the cursor to the end of the current line. |
^ERASE | ^127^008 | Component | erase | Database I/O | Delete all data currently in the component, both in the component and in the database. |
^FIELD | ^255^010 | Field | NFLD or PFLD (navigation only) | Navigation or text editing | Move cursor as ^NEXT_FIELD or ^PREV_FIELD (depending on direction mode), or apply a composite function like REMOVE to a field. |
^FIND_TEXT | ^127^150 | Field | - | Text editing | Search for previously specified string or profile. (See also ^PROFILE.) |
^FIRST | ^255^067 | Field, entity | - | Navigation | Composite function, for use with objects like ^WORD and ^OCCURRENCE (but not with ^FIELD). |
^FIRST_OCC | ^127^037 | Entity | None, but will activate OGF for first occurrence | Navigation | Move cursor to first promptable field of first occurrence in current entity; activate OGF for that occurrence. |
^FIRST_TEXT | ^127^129 | Field | - | Navigation | Move cursor to beginning of text. |
^FONT | ^127^151 | Field | - | Text editing | Choose Uniface character set. |
^FRAME | ^127^089 | Field | - | Text editing | Run the Define Frame form to define a frame. |
^HOME | ^127^022 | Component | - | Navigation | Move cursor to top of form window. |
^HELP | ^127^092 | Field, Entity | help | Services | Activate the help trigger for the current field or, if the trigger is empty, the entity. |
^INS_CHAR | ^127^184 | Field | - | Text editing | Insert character in the ^INS_CHAR buffer. |
^INS_FIELD | ^127^181 | Field | - | Text editing | Insert contents of the ^INS_FIELD buffer. |
^INS_FILE | ^127^180 | Field | - | Data entry | Insert file into current field. This is the same as fileload. The upper limit for the number of characters that can be loaded into a field is 65536. This limit applies to both fileload and the function ^INS_FILE. |
^INS_LINE | ^127^182 | Field | - | Text editing | Insert the contents of the ^INS_LINE buffer. |
^INS_OCC | ^127^043 | Entity | create | Data entry | Insert a new occurrence before the current occurrence, that is, at position $curocc. |
^INS_OVER | ^127^146 | Application | - | Text editing | Toggle Insert/Overstrike mode for unifields. |
^INS_SELECT | ^127^195 | Field | - | Text editing | Insert contents of the ^INS_SELECT buffer, or, if this is empty, the INS_FIELD buffer. |
^INS_TEXT | ^127^177 | Field | - | Text editing | Insert contents of the ^INS_FIELD buffer. |
^INS_WORD | ^127^183 | Field | - | Text editing | Insert contents of the ^INS_WORD buffer. |
^INSERT | ^255^071 | Field, entity | create, if the object is an occurrence | Text editing, data entry | Insert object specified (like ^WORD) in a composite function. When the object is ^OCCURRENCE, same as ^INS_OCC; otherwise, insert contents of buffer for the object. |
^ITALIC | ^127^148 | Field | - | Text editing | Toggle italic character attribute. |
^KEY_HELP | ^127^072 | Application | - | Services | Keyboard layout help. |
^LAST | ^255^068 | Field, entity | - | Navigation | Composite function, used with objects like ^WORD and ^OCCURRENCE (but not with ^FIELD). |
^LAST_OCC | ^127^038 | Entity | None, but will activate getFocus for last occurrence | Navigation | Move cursor to first promptable field of last occurrence in current entity, activate getFocus for that occurrence. |
^LAST_TEXT | ^127^128 | Field | - | Navigation | Move cursor to end of text. |
^LINE | ^255^004 | Field | - | Navigation or text editing | Move cursor as ^NEXT_LINE or ^PREV_LINE (depending on direction mode), or apply a composite function like ^REMOVE to a line. |
^MENU | ^127^101 | Field, Entity | menu | Services | Activate the menu trigger for the current field or, if the trigger is empty, the entity. |
^MESSAGE | ^127^093 | Application | - | Services | Display the message frame. |
^NEXT | ^255^065 | Field, entity | - | Mode toggle or navigation | Set the direction mode ($direction) to Next, or, if specified with an object, a composite navigation function. |
^NEXT_CHAR | ^127^142 | Field | - | Navigation | Move cursor to next character. |
^NEXT_FIELD | ^127^046 | Field | next | Navigation | Activate the next trigger for the current field, or, if the trigger is empty, move cursor to next promptable field. |
^NEXT_LINE | ^127^136 | Field | - | Navigation | Move cursor to beginning of next line. |
^NEXT_OCC | ^127^039 | Entity | None, but will activate getFocus for occurrence | Navigation | Move cursor to first promptable field of next occurrence in current entity, activate getFocus for that occurrence. |
^NEXT_TEXT | ^127^163 | Field | - | Navigation | Move cursor to beginning of the next text section that is not currently visible, below. |
^NEXT_WORD | ^127^140 | Field | - | Navigation | Move cursor to beginning of next word. |
^OCCURRENCE | ^255^011 | Entity | None for navigation, create for add or insert, remove for remove | Navigation or data entry | Give focus to next or previous occurrence (depending on direction mode), or apply a composite function like ^REMOVE to an object. |
^OCC_WINDOW | ^255^015 | Entity | - | Navigation | Scroll the displayed occurrences up (in Next mode) or down (in Previous mode) by as many occurrences as are painted on the form for that entity. |
^PREV | ^255^066 | Field, entity | - | Mode toggle or navigation | Set the direction mode ($direction) to Previous, or, if specified with an object, a composite navigation function. |
^PREV_CHAR | ^127^143 | Field | - | Navigation | Move cursor to previous character. |
^PREV_FIELD | ^127^047 | Field | previous | Navigation | Activate the previous trigger for the current field, or, if the trigger is empty, move cursor to previous promptable field. |
^PREV_OCC | ^127^040 | Entity | None, but will activate OGF for occurrence | Navigation | Move cursor to first promptable field of previous occurrence in current entity, activate the getFocus trigger for that occurrence. |
^PREV_LINE | ^127^137 | Field | - | Navigation | Move cursor to beginning of previous line. |
^PREV_TEXT | ^127^162 | Field | - | Navigation | Move cursor to beginning of the next text section that is not currently visible, above. |
^PREV_WORD | ^127^141 | Field | - | Navigation | Move cursor to beginning of next word. |
^127^098 | Component | Services | Activate the print trigger, or, if trigger is empty, run the Print form. | ||
^PRINT_ATTRIBUTES | ^127^099 | Component | - | Services | Run the Print Job Model form. |
^PROFILE | ^127^087 | Field | - | Text editing | Define string or profile to search for with ^FIND_TEXT function. |
^PULLDOWN | ^127^086 | Component Application | - | Services | Activate a menu bar. In character mode, activate the component-level menu bar, if defined, or the application-level menu bar; toggle between menu bars if both are defined. |
^QUIT | ^127^010 | Component | quit | Session control | Activate the quit trigger (intended to end edit session for current form on a negative note, ignore modifications). |
^QUICK_ZOOM | ^127^096 | Field | - | Services | Zoom current field to maximum zoom size in one step. |
^REFRESH | ^127^067 | Application | - | Services | Refresh the screen. Character mode only. |
^REMOVE | ^255^073 | Field, entity | remove, if the object is an occurrence | Text editing, data entry | Remove the object specified (like ^WORD) in a composite function; all removed objects except for occurrences are written to ^INSERT buffers. |
^REM_CHAR | ^127^172 | Field | - | Text editing | Delete character to right of cursor and write to ^INS_CHAR buffer. |
^REM_FIELD | ^127^166 | Field | - | Text editing | Remove the current selection (or the entire field if nothing is selected) to ^INS_FIELD and ^INS_SELECT buffers. |
^REM_FILE | ^127^192 | Field | - | Text editing |
Write contents of field to a file (this
is the same as the filedump statement).
|
^REM_LINE | ^127^167 | Field | - | Text editing | Remove the current line (from right of cursor) to ^INS_LINE buffer. |
^REM_OCC | ^127^045 | Entity | remove | Text editing | Remove the current occurrence. |
^REM_SELECT | ^127^194 | Field | - | Text editing | Remove selected text to ^INS_SELECT and ^INS_FIELD buffers. |
^REM_WORD | ^127^169 | Field | - | Text editing | Remove current word (from right of cursor) to ^INS_WORD buffer. |
^RESET_SELECT | ^127^196 | Field | - | Text editing | Turn off Select mode. |
^RETRIEVE | ^127^005 | Component | retrieve | Database I/O | Activate the retrieve trigger. |
^RETRIEVE_SEQ | ^127^003 | Component | retrieveSequential | Database I/O | Activate the retrieveSequential trigger. |
^RUB_CHAR | ^127^173 | Field | - | Text editing | Backspace (delete character to left of cursor). |
^RUB_SEL_CHAR | ^127^175 | Field | - | Text editing | Remove selected characters (using Backspace). |
^RULER | ^127^081 | Field | - | Text editing | Ruler definition (run Ruler form). |
^SAVE | ^127^179 | Field | - | Text editing | Write selected text to ^INS_SELECT buffer. |
^SELECT | ^127^193 | Field | - | Text editing | Turn on Select mode. |
^SQL | ^127^097 | Application | - | Services | Run the SQL Workbench form. |
^STORE | ^127^011 | Component | store | Database I/O | Activate the store trigger. |
^SWITCH_KEY | ^127^100 | Application | keyboardSwitch | Services | Activate the keyboardSwitch trigger. |
^TEXT | ^255^009 | Field | - | Navigation or text editing | Move cursor as ^NEXT_TEXT or ^PREV_TEXT (depending on direction mode), or apply a composite function like ^REMOVE to text. |
^TEXT_WINDOW | ^255^014 | Field | - | Navigation | Scroll text up or down, depending on direction mode. |
^TOP_OF_FORM | ^127^020 | Component | - | Navigation | Move cursor to the top of the form. Character mode only. |
^UNDERLINE | ^127^149 | Field | - | Text editing | Toggle underline character attribute. |
^USER_KEY | ^127^091 | Component Application | userKey | Services | Activate the userKey trigger for the current form, or, if the trigger is empty, the application. |
^VIEW | ^127^073 | Application | - | Text editing | Toggle View mode on or off. |
^WORD | ^255^003 | Field | - | Navigation or text editing | Move cursor as ^NEXT_WORD or ^PREV_WORD (depending on direction mode), or apply a composite function like ^REMOVE a word. |
^ZOOM | ^127^095 | Field | - | Services | Zoom the current field. |
Note: If literal text or the contents of a variable or field are used in the macro statement, they may not contain composed characters or characters with attributes, for example, bold, underline, or italics. Only characters in Uniface Font 0 should be used.
A macro statement does not execute the functions supplied as its arguments. Instead, it places its arguments in the event input queue. A macro that is triggered during execution of another macro appends its arguments to those of the first macro, which are already in the event input queue. This means that these arguments are executed after those of the first macro are completed.
The macro statement implicitly
returns 0
. Consequently, any statements in the trigger after a
macro statement are ignored. If you need to place statements after the
macro statement, put the macro statement in an
entry ProcScript module, and call this module instead of using the
macro statement directly.
For example, Form A with
Behavior = Normal
and an accompanying Form B with
Behavior= Menu
. Form B is started via the
menu trigger of form A. When a macro
statement is executed in Form B, the structure editor makes form A active again, executes the
functions specified by macro, then reactivates B via the
menu trigger of A.
Note: Filling the structure editor buffer with the commands, rather than calling the structure editor to execute the commands, means that the macro statement relies on the structure editor being started at some point in the future. If this is not the case (for example, because there is a macro statement in the quit or accept trigger of the first form), you have to run another form that briefly starts the structure editor.
Sending Character Codes to the Structure Editor
The following example sends the character codes for the ^RETRIEVE function to the structure editor when the user starts to enter data in the field:
trigger startModification macro "^127^005" ; this is the code for ^RETRIEVE end; startModification
Putting the Structure Editor into Zoom Mode
The following example puts the structure editor
into Zoom mode and inserts a salutation when the user enters a capital D
($char="D"
):
trigger startModification if ($char = 68) ; "D" if (GENDER = "M") $1 = "Mr." else $1 = "Ms." endif macro "^127^096ear %%$1 %%SURNAME, ^CURSOR_RIGHT" endif end; startModification
Copying Contents of Message Frame to Time-Stamped File
The following example uses the macro statement to copy the contents of the message frame into $selblk. The contents of $selblk are then dumped to a time-stamped file. The ProcScript to do this is in a single form, which can be run at any time during the application, or once the application has ended.
This approach ensures that the structure editor is always activated, and that the functions stored in the keyboard input buffer by the macro statement are never ignored. The form contains a single dummy field; this is all that is required for a successful edit session. The form uses component variables, so the form can be used without fear of overwriting general variables ($1-$99).
operation exec
; Start structure editor
edit NM_FIELD
end; exec
trigger getFocus ; of NM_ENTITY entity
; The space at the end of the macro string ensures that
; the startModification trigger is activated
macro "^MESSAGE^SELECT^TEXT^SAVE^ACCEPT "
end
trigger startModification ; of NM_FIELD
$TIME_NOW$ = $clock
$MINUTES$ = $TIME_NOW$[n]
$SECONDS$ = $TIME_NOW$[s]
$HOURS$ = $TIME_NOW$[H]
filedump $selblk,"MF%%$HOURS$_%%$minutes$.%%$SECONDS$"
exit (1)
end