macro

Place the specified structure editor request in the event input queue of a form component.

macro{/exit}   RequestCodes

Example: macro ^RETRIEVE

Qualifiers

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

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.

Values returned in $status
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.

Structure Editor Functions
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 $curocc+1.

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.
^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.
^PRINT ^127^098 Component print 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.

Normal form with Menu form

Graphical content.

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