@TransferNoteHandle

Maps the external NOTEHANDLE NOTEHANDLE1 to NOTEHANDLE NOTEHANDLE2 and transfers it into the current context.
NOTEHANDLE NOTEHANDLE2 is returned.
@TransferNoteHandle is primarily intended for GLOBAL DEFFN functions in which the fields of a passed NOTEHANDLE are to be accessed.
If field contents are modified in such a GLOBAL DEFFN function, these changes become valid in the original only if a back-transfer is performed.
However, NOTEHANDLE NOTEHANDLE1 should not originate from another task; otherwise, accessing the transferred or original NOTEHANDLE with @Functions that use Notes API functions may cause a server "LookUp Handle" error (result: the server stops).

Example: @TransferNoteHandle(NOTEHANDLE1;NOTEHANDLE2);
Without back-transfer

DELFN:ReportNTH[GLOBAL]();
DEFFN:ReportNTH[GLOBAL](noteh1)
{
   noteh2:=@TransferNoteHandle(noteh1;noteh2);
   @LogReport(noteh1;3);
   @LogReport(noteh2;3);
   @PrtVStack("noteh2";0;2048);
}

The passed NOTEHANDLE noteh1 is transferred into the current context and returned as NOTEHANDLE noteh2, valid in that context.

Example: @TransferNoteHandle(NOTEHANDLE1;NOTEHANDLE2);
With back-transfer

DELFN:ModNTHTestText[GLOBAL]();
DEFFN:ModNTHTestText[GLOBAL](*noteh1)
{
   noteh2:=@TransferNoteHandle(noteh1;noteh2);
   TestText[noteh2]:="Test modification";
   noteh1:=@TransferNoteHandle(noteh2;noteh1); /* back-transfer */
}

The passed NOTEHANDLE noteh1 is transferred into the current context and returned as NOTEHANDLE noteh2, valid in that context.
The field TestText is modified.
To modify the field TestText in the calling context as well, that is, in the CALL invocation, the handle must be transferred back.

Note : This text was machine-translated and may contain inaccuracies.