Accessing the current document in the formula language

For form actions, buttons, hotspots, and field formulas, the current document is the one that's open. For view actions, the current document is the one that's highlighted (not checked). For agents, the current document is the one being acted on according to the build selection and SELECT reserved word criteria.

To read from a field in the current document, name the field or use the @GetField function, which returns the value of the field whose name you specify. When you specify a field name, case does not matter, but the name must exactly match the field name. This function returns null if the value of the specified field is null or the specified field does not exist.

To write to a field in the current document, you must use the FIELD reserved word or the @SetField function. You cannot simply name the field.

• The FIELD reserved word is used in an assignment statement and has the following format. If you omit the FIELD reserved word, the assigned variable is treated as a temporary variable.

  FIELD field-name := expression

• @SetField writes to a field and has the same effect as an assignment statement using the FIELD reserved word. @SetField can be nested in another statement; you cannot do this with the FIELD reserved word. The field name is expressed as a text value, so it can be a variable as well as being the exact name in parentheses. One restriction is that @SetField works only on an existing field; if the field you want to write to does not exist in the document, "declare" it at the beginning of the formula by using it in a FIELD assignment. @SetField has the following format.

  @SetField( field-expression-name; expression )

The DEFAULT reserved word provides a value in the event that a field is not in the document. If the field is available, its value is used. If the field is unavailable, the DEFAULT value is used.

DEFAULT field-name := expression

The @MailSend function mails a document. @MailSend without parameters mails the current document, which must contain a field named SendTo containing the recipients. @MailSend with parameters constructs the document to be mailed from the parameters.

@MailSend
@MailSend( to; cc; bcc; subject; body; fields; flags )

The @DeleteField function deletes a field. You specify it as the expression in a FIELD assignment.

FIELD field-name := @DeleteField

The @DocMark([NoUpdate]) function prevents formula changes to the document from being written to storage. The document is the same after processing by the formula as before. This @function only affects agents.

This table lists @functions that return document and field attributes.

Function	Description
@AllChildren	Selects immediate responses to matched documents; use only in a selection formula.
@AllDescendants	Selects all responses to matched documents; use only in a selection formula.
@AttachmentLengths	Returns the size in bytes of each attachment.
@AttachmentModifiedTimes	Returns the date on which the file attached to the current document was last modified.
@AttachmentNames	Returns the file names of all attached files.
@Attachments	Returns the number of attached files.
@Author	Returns the abbreviated names of all authors.
@DocFields	Returns the names of all the fields in the document.
@DocLength	Returns the size in bytes of the document.
@DocumentUniqueID	Returns the document's unique ID, which is unique across all replicas of the document; in a field, creates a doclink to the current document.
@GetFocusTable	Returns the name, current row, or current column of the table that is in focus.
@InheritedDocumentUniqueID	Returns the unique ID of the parent document; in a field, creates a doclink to the current document.
@IsAvailable(field)	Returns True (1) if a field exists in the document.
@IsDocBeingEdited	Returns True (1) if the document is in Edit mode.
@IsDocBeingLoaded	Returns True (1) if the document is being loaded.
@IsDocBeingMailed	Returns True (1) if the document is being mailed.
@IsDocBeingRecalculated	Returns True (1) if the document is being recalculated.
@IsDocBeingSaved	Returns True (1) if the document is being saved.
@IsNewDoc	Returns True (1) if the document is not yet saved.
@IsResponseDoc	Returns True (1) if the document is a response.
@IsUnavailable(field)	Returns True (1) if a field does not exist in the document.
@NoteID	Returns "NT" followed by the note ID of the document.
@PolicyIsFieldLocked	Returns True (1) if the field is locked by an administration policy.
@Responses	Returns the number of responses to the current document in the current view.