edit

Display the component in preparation for user input.

edit

Forms only:

edit {/modal { /deferred } } | {/nonmodal { /nofocus } } | { /menu | /nowander} {LitFieldName}

In operations: edit/modal {/deferred} | /nonmodal

In exec operation: edit{/menu | /nowander} {LitFieldName}

Qualifiers

Note: Qualifiers are only applicable for Form components.

Qualifiers
Qualifier	Description
/modal	Applicable only to forms. Makes the form instance modal, and displays it ready for editing. In the exec operation, overrides the modality defined by the newinstance statement.
/deferred	Displays the modal Form instance, but defers making it editable until the operation containing the edit statement has executed and returned control to the ProcScript that invoked the operation.
/nonmodal	Makes the Form instance non-modal, and displays it, ready for editing. Overrides the modality defined by the newinstance statement.
/nofocus	Displays the form instance but does not give it focus right away. Focus remains with the form instance that was already active, until explicitly changed by the user. Applicable only to non-modal forms. In the exec operation, overrides the InitialFocus property defined by the newinstance statement.
/menu	Activates the menu trigger at field, entity, form, or application level (whichever is lowest) when the Form appears. Only allowed in exec operation.
/nowander	Restricts the movement of cursor (including next and previous screen). Cursor keys can scroll the field contents but cannot be used to leave a field. When the form is used with the GUI driver, the mouse cannot be used to change the location of the cursor and automatic scroll bars are also disabled. Structure editor functions such as ^NEXT_FIELD, ^PREV_FIELD, and so on, work as normal. Only allowed in exec operation.

Parameters

Parameters
Parameter	Data Type	Description
LitFieldName	Literal	Literal name of a component field in which the cursor should be positioned; do not enclose the name in double quotation marks (`"`). If omitted or not present on the form, the cursor is positioned in the first painted field.

Return Values

Values Returned in $status
Value	Meaning
`0`	Success.
`9`	The user used ^ACCEPT to leave the form that was started with edit.
`10`	The user used ^QUIT to leave the form that was started with edit.
`-1`	The edit statement is not in an exec operation or there are no prompt-able fields on the form.
`-16`	An edit is attempted when in batch mode. Use a test on $batch to avoid this.

Values commonly returned by $procerror following edit
Value	Error constant	Meaning
`-33`	`<UGENERR_BATCH_ONLY>`	Statement not allowed in batch mode. Use a test on $batch to avoid this.
`-1401`	`<UPROCERR_PROMPT>`	Prompted field not valid.
`-1402`	`<UPROCERR_STATEMENT>`	Statement not allowed in this trigger. This can be caused by /menu or /nowander being used in an operation, or using edit in a service.
`-1411`	`<UPROCERR_EDITTWICE>`	An edit statement was encountered when the structure editor was already active. This error also occurs when an activate is performed on a modal form that is already in edit mode and that has an empty exec operation (an implicit edit).

Use

Allowed in the exec operation and operations of Form components. In operations other than exec, it must be followed by a qualifier.

Allowed without qualifiers or arguments in the exec operation of Static Server Pages.

Description

The edit statement is typically used in the exec operation to display the component instance and enable the user to edit the data.

Note: If the exec operation is empty, the edit statement (without qualifiers or argument) is implicitly executed.

In a Form component, it starts the structure editor. If LitFieldName is omitted or not present on the form, the cursor is positioned in the first painted field (that is, in the field nearest the top left corner of the form).

If LitFieldName is present or if the /nowander switch is used, the edit statement causes the getFocus trigger to be activated.

edit in Operations

When using the edit statement in an operation, you should specify the modality using the /modal or /nonmodal switch, and the modality must match the modality of the form.

Any statements after the edit/modal statement are executed when the structure editor session is terminated.

Any statements after the edit/nonmodal statement are immediately executed, that is, processing continues while the structure editor is running.

When edit is used in an operation, as opposed to the exec operation, the form instance remains available even after the operation has completed. This means that the structure editor can be started on a form without the need to recreate the form, and also that the form can be displayed as necessary using the show statement.

Although the edit statement can be used in triggers, it is recommended that it be used only in operations. When a modal form is invoked via edit in its exec operation, that particular instance of the form can no longer be addressed once processing in the exec operation completes.

However, if the form is invoked via edit in an operation, the form will remain instantiated even after the operation has completed. This means that the structure editor can be started on a form without the need to recreate the form, and also that the form can be displayed as necessary using the show statement.

When using the edit statement in an operation, you must specify the modality using either edit/modal or edit/nonmodal.

If an edit/modal or edit/nonmodal statement is executed while the structure editor is running (that is, $interactive returns 1), an error is returned.

edit with Exception Handling

The edit statement is the call stack parent of all interactive triggers of a modal form, and many exceptions bubble through it when exception handling is enabled. To catch a specific exception thrown by an interactive trigger, such as detail, while a modal form is waiting for user input and Uniface is in idle mode, put a try-catch around the edit statement in the exec operation of the modal form.

edit in Web Applications

When edit is encountered (explicitly or implicitly) in a Static Server Page, it acts as a webget followed by a webgen, and an HTML document is prepared and sent to the browser. The LitFieldName argument and the /menu and /nowander switches have no effect.

In Dynamic Server Page components, the edit statement is ignored, whether implicitly or explicitly used.

edit /nofocus

The edit /nofocus command can be useful when you are working with secondary or popup forms and you don't want to give the non-modal form focus right away. For example, in a quick search feature in which potential search terms are displayed in a popup form as you type, focus needs to stay in the edit box but the popup form only get focus when the user clicks on one of the listed terms. You can implement the same behavior by setting the InitialFocus property using when you create a from instance using newinstance.

edit in exec operation

The following example shows the use of edit in an exec operation:

operation exec

CUST_NBR = $1
retrieve
message "Selected customer ready for editing."
edit CUSTNAME

end ; end exec

edit with Parameters

The following example shows how to use the edit statement in the exec operation, using parameter passing to make the Form component self-contained:

operation exec
params
  string CustomerNumber: IN
endparams

CUST_NBR = CustomerNumber
retrieve
edit

end  ; end exec

History
Version	Change
9.6.04 X401	Added /nofocus