FetchValue

Syntax
FetchValue(scrollpath, target_row, [recordname.]fieldname)
where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname,
level2_row, ]] RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL.scrollname, where
scrollname is the same as the scroll levels primary record name.
Description
Use the FetchValue function to return the value of a buffer field in a specific row
of a scroll level.
Note. This function remains for backward compatibility only. Use the Value field
class property instead.
This function is generally used to retrieve the values of buffer fields outside the
current contet! if a buffer field is in the current contet, you can reference it
directly using a "recordname.#fieldname epression.
Event : Fieldchange
&STATISTICS_ACCOUNT =
FetchValue(GL_ACCOUNT_TL!STATISTICS_ACCOUNT" #$%
I& &STATISTICS_ACCOUNT = '(' Then
)E*IVE)!E)IT_ACCOUNT = *ec+,d!GL_ACCT_STA_V-.%
Event : *+/init
01 2ide the +3en ite4 &ield5 i& 6S0GL and 6S0A6 a,e n+t in5talled 10
I& INSTALLATION!GL = 'N' And
INSTALLATION!A6 = 'N' Then
I& Cu,,ent*+/Nu47e,($ = # Then
2ide(GL_ACCOUNT_TL!O6EN_ITE8$%
ActiveRowCount
Syntax
ActiveRowCount(Scrollpath)
$here scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]]
RECORD.target_recname
To prevent ambiguous references, you can use SCROLL. scrollname, where scrollname is the
same as the scroll levels primary record name.
Description
Use the %ctive&ow'ount function to return the number of active (non)deleted* rows for a
specified scroll area in the active page.
Note. This function remains for backward compatibility only. Use the %ctive&ow'ount &owset
class property instead.
%ctive&ow'ount is often used to get a limiting value for a For statement. This enables you to loop
through the active rows of a scroll area, performing an operation on each active row. &ows that
have been marked as deleted are not affected in a For loop delimited by %ctive&ow'ount. +f you
want to loop through all the rows of a scroll area, including deleted rows, use Total&ow'ount.
Use %ctive&ow'ount with 'urrent&ow,umber to determine whether the user is on the last row of
a record.
Returns
&eturns a ,umber value e-ual to the total active (non)deleted* rows in the specified scroll area in
the active page.
Example
+n this eample ActiveRowCount is used to delimit a For loop through a level)one scroll:
&CURRENT_L1 = CurrentRowNumber(1);
&ACTIVE_L = A!t"#eRowCount(REC$R%.A&&I'N(ENT, &CURRENT_L1,
REC$R%.A&'N_)$(E_)$&T);
&)$(E_)$&T = *et!+V,-ue(REC$R%.A&&I'N(ENT, &CURRENT_L1,
A&'N_)$(E_)$&T.)$(E_)$&T, 1);
I. A--(&)$(E_)$&T) T+en
*or &I = 1 To &ACTIVE_L
%e-eteRow(REC$R%.A&&I'N(ENT, &CURRENT_L1, REC$R%.A&'N_)$(E_)$&T, 1);
En/0*or;
En/0I.;
All
Syntax
All(fieldlist)
$here fieldlist is an arbitrary)length list of field names in the form:
[recordname.]fieldname1 [, [recordname.]fieldname2] ...
Description
Use the %ll function to verify if a field contains a value, or if all the fields in a list of fields contain
values. +f any of the fields are ,ull, then %ll returns False.
% blank character field, or a .ero (/* numeric value in a re-uired numeric field is considered a null
value.
Relate Functions
None 'hecks that a field or list of fields have no value.
AllOrNone 'hecks if either all the field parameters have values, or none of them have
values. Use this in eamples where if the user fills in one field, she must fill in
all the other related values.
OnlyOne 'hecks if eactly one field in the set has a value. Use this when the user must
fill in only one of a set of mutually eclusive fields.
OnlyOneOrNone 'hecks if no more than one field in the set has a value. Use this in eamples
when a set of fields is both optional and mutually eclusive! that is, if the user
can put a value into one field in a set of fields, or leave them all empty.
Returns
&eturns a 0oolean value based on the values in fieldlist. The %ll function returns True if all of the
specified fields have a value! it returns False if any one of the fields does not contain a value.
Example
The %ll function is commonly used in 1ave2dit 3eople'ode to ensure that a group of related
fields are all entered. For eample:
I. A--(RETURN_%T, 1E'IN_%T) ,n/
2 3 (RETURN_%T 0 1E'IN_%T) (%URATI$N_%A4& 3 2 5 %URATI$N_)$UR&)
T+en
6,rn"n7 (87'et(1999, 1, :%ur,t"on o. ,b8en!e e;!ee/8 8t,n/,r/ +our8 .or
number o. /,<8 ,b8ent.:);
En/0".;
Commit!or"
Syntax
CommitWork()
Description
Use the 'ommit$ork function to commit pending changes (inserts, updates, and deletes* to the
database.
Consierations #or $sin% Commit!or"
The following are the considerations for using 'ommit$ork.
This function is available in %pplication 2ngine 3eople'ode, the Field'hange and
1ave3re'hange events, and 4essage 1ubscription 3eople'ode. +f you use it anywhere
else, you5ll receive a runtime error.
$hen used with an %pplication 2ngine program, this function only applies to those
%pplication 2ngine programs that run in batch (not online*. +f the program is invoked
using the 'all%pp2ngine function, the 'ommit$ork call is ignored. The same is true for
commit settings at the section or step level.
This function can only be used in an %pplication 2ngine program that has restart
disabled. +f you try to use this function in a program that doesn5t have restart disabled,
you5ll receive a runtime error.
'omponent interfaces that rely on 'ommit$ork to save data cannot be used in the 2cel
to 'omponent +nterface utility.
$hen 'ommit$ork is called in the contet of a component interface (such as, during a
1ave3re'hange 3eople'ode program that5s associated with the component*, if the caller
of the component interface already has an open cursor (such as an active 167 ob8ect*
the 'ommit does not take effect immediately, but only when the last cursor is closed.
1ee 'all%pp2ngine.
FielChan%e an Save&reChan%e Consierations
The following are the Field'hange and 1ave3re'hange considerations:
%ll updates done in Field'hange (including those using 'all%pp2ngine* should be
considered a single database transaction. This is a fundamental change: previously, a
single transaction was represented by a page or a component.
% conse-uence of this is that a message re-uiring a reply, or any other think)time action,
causes a fatal error if located in Field'hange after a database update that has not been
committed to the database using the 'ommit$ork function. 1o it is possible for an
application to update the database in Field'hange, then do a think)time action, by
preceding the think)time action with a call to 'ommit$ork.
'ommit$ork commits the updates and closes the database transaction (that is, the unit
of work*. The conse-uence of using 'ommit$ork is that because it closes the database
transaction, any subse-uent rollback calls will not rollback the committed updates.
9ust as any database updates in Field'hange re-uired careful application design to
ensure that the transaction model is appropriate, so too does the use of 'ommit$ork.
$hen using 'ommit$ork in the 'omponent 3rocessor environment (as opposed to
using it in an %pplication 2ngine program* 'ommit$ork produces an error if there are
any open cursors, such as any open 3eople'ode 167 ob8ects.
1ee Field'hange 2vent.
Application En%ine Consierations
The 'ommit$ork function is useful only when you are doing row)at)a)time 167 processing in a
single 3eople'ode program, and you must commit without eiting the program. +n a typical
%pplication 2ngine program, 167 commands are split between multiple %pplication 2ngine
actions that fetch, insert, update, or delete application data. Therefore, you would use the section
or step level commit settings to manage the commits. This is the recommended approach.
:owever, with some types of %pplication 2ngine programs that are 3eople'ode intensive, it can
be difficult to eit the 3eople'ode in order to perform a commit. This is the only time when the
'ommit$ork function should be used.
1ee &estarting %pplication 2ngine 3rograms.
Restart Consierations
;isabling restart on a particular program means that the application itself is intrinsically self)
restartable: it can be re)run from the start after an abend, and it performs any initiali.ation,
cleanup, and filtering of input data to ensure that everything gets processed once and only once,
and that upon successful completion, the database is in the same state it would have been if no
abend occurred.
1et)based applications should always use %pplication 2ngine5s restart. <nly row)by)row
applications that have restart built into them can benefit from disabling %pplication 2ngine5s
restart.
'onsider the following points to managing restarts in a self)restarting program:
7ocking input transactions (optional*.
+f the input data can change, and if it5s important not to pick up new data during a restart,
there should be logic to lock transactions at the start of the initial run (such as updating
rows with current 3rocess +nstance*. The program should first check whether any rows
have the current 3rocess +nstance (that is, is the process being restarted from the top
after an abend=*. +f no rows found, do the update.
+n some cases it is acceptable for a restarted process to pick up new rows, so that
locking is not necessary. +t depends on your application.
%lso, if you don5t lock transactions, you must provide some other way to manage
concurrent processing of the same program. >ou don5t want two simultaneous runs of the
same program to use the same data, so you must have some strategy for dividing up the
data such that there is no overlap.
Filtering input transactions (re-uired*.
%fter an input transaction is processed, the row should be updated accordingly (that is,
setting a ?processed? flag*. The 1272'T statement that drives the main processing loop
should include a $:2&2 condition to filter out rows that have already been processed.
'essa%in% Consierations
>ou are responsible for coding any restart ability in messaging 3eople'ode if you use the
'ommit$ork function. ,ormally, the system rolls back the transaction in the event of a
3eople'ode failure. This is not a problem, because the subscription can safely run again.
:owever, if 'ommit$ork has already been issued! data changes have already been saved and
cannot be rolled back. +t is important that a subse-uent run of the subscription 3eople'ode can
work without error and not mishandle the previously saved data.
Returns
% 0oolean value, True if data was successfully committed, False otherwise.
Example
The following eample fetches rows and processes them one at a time, committing every @//
iterations. 0ecause restart is disabled, you must have a marker indicating which rows have been
processed, and use it in a conditional clause that filters out those rows.
Lo!,- &=L &&=L;
Lo!,- Re!or/ &REC;
Lo!,- Number &C$UNT;

&REC = Cre,teRe!or/(REC$R%.TRAN&_T1L);
&&=L = Cre,te&=L(:>&e-e!tA--(?1) 6)ERE @R$CE&&E% AB C4C:);
&C$UNT = 9;

&&=L.E;e!ute(&REC);
6+"-e &&=L.*et!+(&REC)
I. (&C$UNT B DD) T+en
&C$UNT = 9;
Comm"t6orE(); F3 !omm"t worE on!e Ger 199 "ter,t"on8 3F
En/0".;
&C$UNT = &C$UNT 5 1;
F3 /o Gro!e88"n7 3F
...

F3 uG/,te tr,n8,!t"on ,8 :Gro!e88e/: 3F
&REC.@R$CE&&E%.V,-ue = C4C;
&REC.UG/,te();
En/06+"-e;
Component
Syntax
Component data_type &var_name
Description
Use the 'omponent statement to declare 3eople'ode component variables. % component
variable, after being declared in any 3eople'ode program, remains in scope throughout the life of
the component.
The variable must be declared with the 'omponent statement in every 3eople'ode program in
which it is used.
;eclarations appear at the beginning of the program, intermied with function declarations.
Note. 0ecause a function can be called from anywhere, you cannot declare any variables within a
function. >ou receive a design time error if you try.
The system automatically initiali.es temporary variables. ;eclared variables always have values
appropriate to their declared type. Undeclared variables are initiali.ed as null strings.
,ot all 3eople'ode data types can be declared as 'omponent.
&arameters
dataAtype 1pecify a 3eople'ode data type.
Bvar_name % legal variable name.
Example
ComGonent 8tr"n7 &@'_*IR&T;
CopyFiels
Syntax
CopyFields(from, to)
where from and to are constructions that reference rows of data on specific source and target
records in the component buffer! each have the following synta:
level, scrollpath, target_row
and where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]]
RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL. scrollname, where scrollname is
the same as the scroll levels primary record name.
Description
Use the 'opyFields function to copy like)named fields from a row on the specific source record to
a row on the specific target record.
Note. This function remains for backward compatibility only. Use the 'opyFieldsTo or
'opy'hangedFieldsTo record class methods instead.
&arameters
from % placeholder for a construction (level, scrollpath, target_row* that references the first
row in the comparison.
to % placeholder for a construction (level, scrollpath, target_row* that references the
second row in the comparison.
level 1pecifies the scroll level for the target level scroll.
scrollpath % construction that specifies a scroll level in the component buffer.
target_row 1pecifies the row number of each target row on its scroll level.
Returns
<ptionally returns a 0oolean value indicating whether the function succeeded.
Example
The following eample copies fields from 3<A&2'2+V2;A+,V (level @ scroll* from row B&<$ to
3<A&2'VA+,VAV$ (level @ scroll*, row B7<'A&<$:
CoG<*"e-/8(1, REC$R%.@$_RECEIVE%_INV, &R$6, 1, REC$R%.@$_RECV_INV_V6, &L$C_R$6);
See Also
CurrentRowNum(er
Syntax
CurrentRowNumer([level])
Description
Use the 'urrent&ow,umber function to determine the row number of the row currently displayed
in a specific scroll area.
Note. This function remains for backward compatibility only. Use the &ow,umber row class
property instead.
This function can determine the current row number on the level where the function call resides,
or on a higher scroll level. +t wont work on a scroll level below the one where the 3eople'ode
program resides.
See Also
Cet&ow, &ow,umber.
%ccessing the ;ata 0uffer
&arameters
level % ,umber specifying the scroll level from which the function returns the current row number.
+f the level parameter is omitted, it defaults to the scroll level where the function call resides.
Returns
&eturns a ,umber value e-ual to the current row number on the specified scroll level. The current
number is the row where the 3eople'ode program is being processed, or, if level specifies a
higher level scroll, 'urrent&ow,umber returns the row number of the parent or grandparent row.
Example
'urrent&ow,umber is typically used in component buffer functions to return the current row of
the parent scroll of the target:
&VAL = *et!+V,-ue(REC$R%.1U&_EH@EN&E_@ER, CurrentRowNumber(),
1U&_EH@EN&E_%TL.C)AR'E_%T, &C$UNT);
The following eample checks if the current row number is e-ual to the active row count (that is,
whether the active row is the last record on the scroll*:
I. CurrentRowNumber() = A!t"#eRowCount(E(@LI%) T+en
/et_emG-o<ment_/t();
En/0".;
Declare Function
Syntax
3eople'ode Function 1ynta
Declare Function function_name !eopleCode record_name.field_name event_type
DeleteRecor
Syntax
DeleteRecord(level_zero_recfield)
Description
Use the ;elete&ecord function to remove a high)level row of data and all dependent rows in other
tables from the database.
Note. This function remains for backward compatibility only. Use the ;elete record class method
instead.
;elete&ecord deletes the components level).ero row from the database, deletes any dependent
rows in other tables from the database, and eits the component.
This function, like ;elete&ow, initially marks the record or row as needing to be deleted. %t save
time the row is actually deleted from the database and cleared from the buffer.
This function works only if the 3eople'ode is on a level).ero field. +t cannot be used from
1ave3ost'hange or $orkFlow 3eople'ode.
See Also
;elete, %ccessing the ;ata 0uffer.
&arameters
level_zero_recfield % recordname.fieldname reference identifying any field on the level).ero area
of the page.
Returns
<ptionally returns a 0oolean value indicating whether the deletion was completed successfully.
Example
The following eample, which is in 1ave3re'hange 3eople'ode on a level).ero field, deletes the
high)level row and all dependent rows in other tables if the current page is
2437<>22A+;A;272T2.
". >@,7e = @A'E.E(@L$4EE_I%_%ELETE t+en
&8u!!e88 = %e-eteRe!or/(E(@LI%);
en/0".;
DoCancel
Syntax
DoCancel( )
Description
Use the ;o'ancel function to cancel the current page.
+n the 3age %pplet, the ;o'ancel function terminates the current component and returns
the user to the search dialog bo.
+n the 4enu %pplet, the ;o'ancel function terminates the current component and returns
the user to the current menu with no component active.
;o'ancel terminates any 3eople'ode programs eecuting prior to a save action. +t does not stop
processing of 3eople'ode in 1ave2dit, 1ave3re'hange, and 1ave3ost'hange events.
Returns
,one.
Do'oal
Syntax
Do"odal(!A#E.pagename, title, xpos, ypos,
[level, scrollpath, target_row])
where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]]
RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL. scrollname, where scrollname is
the same as the scroll levels primary record name.
Description
Use the ;o4odal function to display a secondary page. 1econdary pages are modal, meaning
that the user must dismiss the secondary page before continuing work in the page from which the
secondary page was called.
+f you call ;o4odal without specifying a level number or any record parameters, the function uses
the current contet as the parent.
>ou can alternately specify a secondary page in a command push button definition without using
3eople'ode. This may be preferable for performance reasons, especially with 3eople1oft 3ure
+nternet %rchitecture.
;o4odal can display on a single page. To display an entire component modally, use
;o4odal'omponent.
%ny variable declared as a 'omponent variable will still be defined after using a ;o4odal
function.
1ee Using 1econdary 3ages.
Restrictions on $se in &eopleCoe Events
'ontrol does not return to the line after ;o4odal until after the user has dismissed the secondary
page. This interruption of processing makes ;o4odal a Dthink)timeE function, which means that it
shouldnt be used in any of the following 3eople'ode events:
1ave3re'hange.
1ave3ost'hange.
$orkflow.
&ow1elect.
%ny 3eople'ode event that fires as a result of a 1croll1elect (or one of its relatives*
function calls, or a 1elect (or one of its relatives* &owset class method.
+n addition, you can5t use this function in the 1earch+nit event.
1ee Think)Time Functions.
Restrictions on $se !ith a Component )nter#ace
This function is ignored (has no effect* when used by a 3eople'ode program thats been called
by a 'omponent +nterface.
Consierations $sin% Exceptions an the Do'oal Function
Using the ;o4odal function inside a try block not catch 3eople'ode eceptions thrown in the
new component. 1tarting a new component starts a brand new 3eople'ode evaluation contet.
'atches are only caught for eceptions thrown within the current component.
+n the following code eample, the catch statement only catches eceptions thrown in the code
prior to the ;o4odal, but not any eceptions that are thrown within the new component.
F3 &et uG tr,n8,!t"on 3F
I. >ComGInt.!N,me = :: T+en
tr<
&oTr,n8 =
&7_ER(&_Tr,n8,!t"onCo--e!t"on.'etTr,n8,!t"on1<N,me(R1_E(_6RI.%E&CR);
&8&e,r!+@,7e = &oTr,n8.&e,r!+@,7e;
&8&e,r!+Re!or/ = &oTr,n8.&e,r!+Re!or/;
&8&e,r!+T"t-e = &oTr,n8.'et&e,r!+@,7eT"t-e();
I. Not A--(&8&e,r!+@,7e, &8&e,r!+Re!or/, &8&e,r!+T"t-e) T+en
Error ((87'etTe;t(1J2KL, 2921, :(e88,7e Not *oun/:));
En/0I.;
&!_ER(&_&e,r!+Tr,n8,!t"on = &oTr,n8;

F3 AttemGt to tr,n8.er to +"//en 8e,r!+ G,7e w"t+ !on."7ur,b-e ."-ter 3F
&n(o/,-Return = Do"odal(M(:@,7e.: N &8&e,r!+@,7e), &8&e,r!+T"t-e, 0 1, 0
1);
!,t!+ E;!eGt"on &e
Error ((87'etTe;t(1J2KL, 292, :(e88,7e Not *oun/:));
en/0tr<;
&arameters
pagename The name of the secondary page.
title The tet that displays in the caption of the secondary page.
xpos The piel coordinates of the top left corner of the secondary page, offset from the top
left corner of the parent page (the default of )@, )@ means centered*.
ypos The piel coordinates of the top right corner of the secondary page, offset from the top
right corner of the parent page (the default of )@, )@ means centered*.
level 1pecifies the level of the scroll level on the parent page that contains the row
corresponding to level / on the secondary page.
scrollpath % construction that specifies a scroll level in the component buffer.
target_row The row number of the row in the parent page corresponding to the level / row in the
secondary page.
Returns
&eturns a number that indicates how the secondary page was terminated. % secondary page can
be terminated by the user clicking a built)in <F or 'ancel button, or by a call to the 2nd4odal
function in a 3eople'ode program. +n either case, the return value of ;o4odal is one of the
following:
@ if the user clicked <F in the secondary page, or if @ was passed in the 2nd4odal
function call that terminated the secondary page.
/ if the user clicked 'ancel in the secondary page, or if / was passed in the 2nd4odal
function call that terminated the secondary page.
Example
%o(o/,-(@A'E.E%UCATI$N_%TL, (87'etTe;t(1999, 1OJ, :E/u!,t"on %et,"-8 0 >1:,
E%UCATN.%E'REE), 0 1, 0 1, 1, REC$R%.E%UCATN,
CurrentRowNumber());
Do'oalComponent
Syntax
Do"odalComponent("EN$NA"E.menuname, %ARNA"E.barname, &'E"NA"E.menuitem_name,
!A#E.component_item_name, action, RECORD.shared_record_name [, eylist])
where keylist is a list of field references in the form:
[recordname.]field1 [, [recordname.]field2]. . .
<r
!"ecord#b$ect1 [, !"ecord#b$ect2]. . .
Description
Use the ;o4odal'omponent function to launch a modal component. The modal component
launches from within an originating component. %fter the modal component displays, the user
cant proceed with changes to the originating component until either accepting or canceling the
modal component.
4odal components can be displayed in any of the following action modes: %dd, UpdateG;isplay,
UpdateG;isplay %ll, 'orrection. % modal component can be launched from any component,
including another modal component. >ou can use ;o4odal'omponent from a secondary page.
The originating component and the modal component share data, including search keys, using a
1hared $ork &ecord or the values in the fieldlist parameter. +f valid search keys are provided in
the shared work record and populated with valid values before launching the modal component,
the search is conducted using the provided search key values. +f the fieldlist parameter isn5t used
and no search keys are provided, or if search key fields contain invalid values, the user accesses
the modal component using a search dialog bo.
Note. The user may see a different title for a search page if they enter the search page using this
function versus from the regular navigation.
+n the component_item_name parameter, make sure to pass the component item name for the
page, not the page name. The component item name is specified in the 'omponent ;efinition, in
the +tem ,ame column on the row corresponding to the specific page, as shown here:
'omponent +tem ,ame parameter
Share !or" Recors
The originating component and the modal component share fields in a ;erivedG$ork record
called a shared work record. 1hared fields from this record must be placed at level .ero of both
the originating component and the modal component.
>ou can use the shared fields to:
3ass values that are assigned to the search keys in the modal component search record.
+f these fields are missing or not valid, the search dialog bo appears, enabling the user
to enter search keys.
<ptionally pass other values from the originating component to the modal component.
3ass values back from the modal component to the originating component for
processing.
To do this, you have to write 3eople'ode that:
%ssigns values to fields in the shared work record in the originating page at some point
before the modal transfer takes place.
%ccesses and changes the values, if necessary, in the modal component.
%ccesses the values from the shared work record from the originating component after
the modal component is dismissed.
Restrictions on $se !ith a Component )nter#ace
This function is ignored (has no effect* when used by a 3eople'ode program thats been called
by a 'omponent +nterface.
Restrictions on $se !ith Search)nit Event
>ou can5t use this function in a 1earch+nit 3eople'ode program.
Consierations $sin% Exceptions an the Do'oalComponent Function
Using the Do'oalComponent function inside a try block not catch 3eople'ode eceptions
thrown in the new component. 1tarting a new component starts a brand new 3eople'ode
evaluation contet. 'atches are only caught for eceptions thrown within the current component.
+n the following code eample, the catch statement only catches eceptions thrown in the code
prior to using a ;o4odal function, but not any eceptions that are thrown within the new
component.
F3 &et uG tr,n8,!t"on 3F
I. >ComGInt.!N,me = :: T+en
tr<
&oTr,n8 =
&7_ER(&_Tr,n8,!t"onCo--e!t"on.'etTr,n8,!t"on1<N,me(R1_E(_6RI.%E&CR);
&8&e,r!+@,7e = &oTr,n8.&e,r!+@,7e;
&8&e,r!+Re!or/ = &oTr,n8.&e,r!+Re!or/;
&8&e,r!+T"t-e = &oTr,n8.'et&e,r!+@,7eT"t-e();
I. Not A--(&8&e,r!+@,7e, &8&e,r!+Re!or/, &8&e,r!+T"t-e) T+en
Error ((87'etTe;t(1J2KL, 2921, :(e88,7e Not *oun/:));
En/0I.;
&!_ER(&_&e,r!+Tr,n8,!t"on = &oTr,n8;

F3 AttemGt to tr,n8.er to +"//en 8e,r!+ G,7e w"t+ !on."7ur,b-e ."-ter 3F
&n(o/,-Return = Do"odal(M(:@,7e.: N &8&e,r!+@,7e), &8&e,r!+T"t-e, 0 1, 0
1);
!,t!+ E;!eGt"on &e
Error ((87'etTe;t(1J2KL, 292, :(e88,7e Not *oun/:));
en/0tr<;
&arameters
menuname ,ame of the menu through which the modal component is accessed.
barname ,ame of the menu bar through which the modal component is accessed.
menuitem_name ,ame of the menu item through which the modal component is accessed.
component_item_name The component item name of the page to be displayed on top of the
modal component when it displays. The component item name is
specified in the component definition.
action 1tring representing the action mode in which to start up the component.
>ou can use either a character value (passed in as a string* or a constant
En'oal
Syntax
End"odal(returnvalue)
Description
Use the 2nd4odal function to close a currently open secondary page. +t is re-uired only for
secondary pages that do not have <F and 'ancel buttons. +f the secondary page has <F and
'ancel buttons, then the function for eiting the page is built in and no 3eople'ode is re-uired.
Restrictions on $se !ith a Component )nter#ace
This function is ignored (has no effect* when used by a 3eople'ode program thats been called
by a 'omponent +nterface.
&arameters
returnvalue % ,umber value that determines whether the secondary page data is copied back to
the parent page. % positive value runs 1ave2dit 3eople'ode and copies the data (this
is the same as clicking the <F button*. % value of .ero skips 1ave2dit and discards
buffer changes made in the secondary page (this is the same as clicking the 'ancel
button*. This value becomes the return value of the ;o4odal function that started the
secondary page, and it can be tested after the secondary page is closed.
Returns
,one.
Example
The following statement acts as an <F button:
En/(o/,-(1);
The following statement acts as a 'ancel button:
En/(o/,-(9);
DoSave
Syntax
Do(ave()
Description
Use the ;o1ave function to save the current page. ;o1ave defers processing to the end of the
current 3eople'ode program event, as distinct from ;o1ave,ow, which causes save processing
(including 1ave2dit, 1ave3re'hange, 1ave3ost'hange, and $orkflow 3eople'ode* to be
eecuted immediately.
;o1ave can be used only in Field2dit, Field'hange, or 4enu+tem1elected 3eople'ode.
&arameters
,one.
Returns
,one.
Example
The following eample sets up a key list with %ddFey7ist+tem, saves the current page, and then
transfers the user to a page named 3%C2AH.
C-e,rIe<L"8tItem( );
A//Ie<L"8tItem($@RI%, $@RI%);
A//Ie<L"8tItem(RE=UE&T_I%, RE=UE&T_I%);
&etNe;t@,7e(:@A'E_:);
%o&,#e( );
Tr,n8.er@,7e( );
FielChan%e
Syntax
The synta of the Field'hanged function varies depending on whether you want to use a scroll
path reference or a contetual reference to specify the field.
+f you want to use a scroll path reference, the synta is:
FieldChan)ed(scrollpath, target_row, [recordname.]fieldname)
where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]]
RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL.scrollname, where scrollname is
the same as the scroll levels primary record name.
+f you want to use a contetual reference, the synta is:
FieldChan)ed([recordname.]fieldname)
+n this construction the scroll level and row number are determined based on the current contet.
Description
The Field'hanged function returns True if the referenced buffer field has been modified since
being retrieved from the database either by a user or by a 3eople'ode program.
Note. This function remains for backward compatibility only. Use the +s'hanged field class
property instead.
This is useful during 1ave3re'hange or 1ave3ost'hange processing for checking whether to
make related updates based on a change to a field.
See Also
+s'hanged.
%ccessing the ;ata 0uffer
1pecifying ;ata with &eferences Using 1croll 3ath 1ynta and ;ot ,otation
&arameters
scrollpath % construction that specifies a scroll level in the component buffer.
"recordname.#fieldname The name of the field where the value to check is located. The field can
be on scroll level one, two, or three of the active page. The recordname
prefi is re-uired if the call to Field'hanged is in a record definition other
than recordname.
target_row The row number of the target row. +f this parameter is omitted, the
function assumes the row on which the 3eople'ode program is
eecuting.
Relate Functions
1ave 3eople'ode programs (1ave2dit, 1ave3re'hange, 1ave3ost'hange* normally process
each row of data in the component. The following four functions enable you to control more
precisely when the 'omponent 3rocessor should perform save 3eople'ode:
Field'hanged
&ecord'hanged
&ecord;eleted
&ecord,ew
These functions enable you to restrict save program processing to specific rows.
Example
The following eample checks three fields and sets a flag if any of them has changed:
F3 &et t+e net !+,n7e .-,7 to C4e8C ". t+e 8!+e/u-e/ /,te, 8!+e/u-e/ 3F
F3 t"me or Pu,nt"t< rePue8te/ "8 !+,n7e/ 3F
I. *"e-/C+,n7e/(=T4_RE=UE&TE%) $r
*"e-/C+,n7e/(&C)E%_%ATE) $r
*"e-/C+,n7e/(&C)E%_TI(E) T+en
NET_C)AN'E_*L' = :4:;
En/0I.;
Function
Syntax
Function name [(paramlist%] [Returns data_type]
[statements]
End*+unction
$here paramlist is:
!param1 [As data_type] [, !param2 [As data_type]]...
$here data_type is any valid data type, including ,umber, 1tring, ;ate, &owset, 167, &ecord,
and so on.
$here statements is a list of 3eople'ode statements.
Description
3eople'ode functions can be defined in any 3eople'ode program. Function definitions must be
placed at the top of the program, along with any variable and eternal function declarations.
Functions can be called from the program in which they are defined, in which case they dont
need to be declared, and they can be called from another program, in which case they need to be
declared at the top of the program where they are called.
%ny variables declared within a function are valid for the scope of the function.
0y convention, eternal 3eople'ode functions are stored in records whose names begin in
FU,'7+0A, and they are always placed in the FieldFormula event (which is convenient because
this event should no longer be used for anything else*.
Note. Functions can be stored in the FieldFormula event only for record fields, not for component
record fields.
% function definition consists of:
The keyword Function followed by the name of the function and an optional list of
parameters. The name of the function can be up to @// characters in length.
%n optional &eturns clause specifying the data type of the value returned by the function.
The statements to be eecuted when the function is called.
The 2nd)function keyword.
The parameter list, which must be enclosed in parentheses, is a comma)separated list of variable
names, each prefied with the B character. 2ach parameter is optionally followed by the keyword
%s and the name for one of the conventional 3eople'ode data types (,umber, 1tring, ;ate, and
so on* or any of the ob8ect data types (such as &owset, 167, and so on.* +f you specify data
types for parameters, then function calls are checked to ensure that values passed to the function
are of the appropriate type. +f data types are not specified, then the parameters, like other
temporary variables in 3eople'ode, take on the type of the value that is passed to them.
3eople'ode parameters are always passed by reference. This means that if you pass the
function a variable from the calling routine and change the value of the variable within the
function, the value of the variable is changed when the flow of eecution returns to the calling
routine.
+f the function is to return a result to the caller, the optional &eturns part must be included to
specify the data type of the returned value. >ou have seven choices of value types: ,umber,
1tring, ;ate, Time, ;ateTime, 0oolean, or %ny.
3eople'ode internal subroutines are part of the enclosing program and can access the same set
of variables as the other statement)lists of the program, in addition to local variables created by
the parameters and local variable declarations within the function.
Returnin% a Value
>ou can optionally return a value from a 3eople'ode function. To do so, you must include a
Return statement in the function definition, as described in the preceding section. For eample,
the following statement returns a ,umber value:
.un!t"on !,-!_8omet+"n7(&G,rm1 ,8 number, &G,rm ,8 number) return8 number
+n the code section of your function, use the &eturn statement to return a value to the calling
routine. $hen the &eturn statement eecutes, the function ends and the flow of eecution goes
back to the calling routine.
Example
This eample returns a 0oolean value based on the return value of a 1672ec:
.un!t"on run_8t,tu8_uG/(&@R$CE&&_IN&TANCE, &RUN_&TATU&) return8 1oo-e,n;
&U@%ATE$I = &=LE;e!(:uG/,te @&_@RC&_R=&T 8et run_8t,tu8 = ?1 w+ere
Gro!e88_"n8t,n!e = ?:, &RUN_&TATU&, &@R$CE&&_IN&TANCE);
I. &U@%ATE$I T+en
Return True;
E-8e
Return *,-8e;
En/0".;
En/0.un!t"on;
*etFiel
Syntax
#etField([recname.fieldname])
Description
Use the CetField function to create a reference to a field ob8ect for the current contet! that is,
from the row containing the currently eecuting program.
+f you don5t specify recname.fieldname, the current field eecuting the 3eople'ode is returned.
Note. For 3eople'ode programs located in events that are not associated with a specific row,
record, and field at the point of eecution this function is invalid. That is, you cannot use this
function in 3eople'ode programs on events associated with high)level ob8ects like pages or
components. For events associated with record level programs (like component record*, this
function is valid, but it must be specified with a field name, as there is an assumed record, but no
assumed field name.
$hen CetField is used with an associated record and field name on component buffer data, the
following is assumed:
&*IEL% = 'etRow().re!n,me.."e-/n,me;
&arameters
recname.fieldname +f you don5t want to refer to the field eecuting the 3eople'ode, specify a
record name and field name.
Returns
This function returns a field ob8ect that references the field from the specified record.
Example
Lo!,- *"e-/ &C)ARACTER;

&C)ARI% = 'et*"e-/(*IEL%.C)AR_I%);
*etFile
Syntax
#etFile(filename, mode [, charset] [, pathtype])
Description
Use the CetFile function to instantiate a new file ob8ect from the File class, associate it with an
eternal file, and open the file so you can use File class methods to read from or write to it.
CetFile is similar to the <pen file class method, but <pen associates an existing file ob8ect with
an eternal file. +f you plan to access only one file at a time, you need only one file ob8ect. Use
CetFile to instantiate a file ob8ect for the first eternal file you access, then use <pen to associate
the same file ob8ect with as many different eternal files as you want. >ou need to instantiate
multiple file ob8ects with CetFile only if you epect to have multiple files open at the same time.
Example
The following eample opens an eisting Unicode file for reading:
&(4*ILE = 'et*"-e(&&$(ENA(E, :E:, :U:);
I. &(4*ILE.I8$Gen T+en
w+"-e &(4*ILE.Re,/L"ne(&&$(E&TRIN');
F3 @ro!e88 t+e !ontent8 o. e,!+ &&$(E&TRIN' 3F
En/06+"-e;
&(4*ILE.C-o8e();
En/0I.;
The following eample opens a numbered file for writing in a non)Unicode format, without
overwriting any eisting files:
&(4*ILE = 'et*"-e(:!?QtemGQ"tem3.t;t:, :N:, >*"-e@,t+_Ab8o-ute);
I. &(4*ILE.I8$Gen T+en
&(4*ILE.6r"teL"ne(:&ome te;t.:);
&(4*ILE.C-o8e();
En/0I.;
The following eample uses the ':%&12T field to indicate the character set to be used:
&(4*ILE = 'et*"-e(:IN@UT.%AT:, :R:, REC$R%.C)AR&ET);
*etLevel+
Syntax
#et-evel.()
Description
Use the Cet7evel/ function to create a rowset ob8ect that corresponds to level / of the
component buffer. +f used from 3eople'ode that isnt associated with a page, it returns the base
rowset from the current contet.
&arameters
Cet7evel/ has no parameters. :owever, it does have a default method, Cet&ow, and a shortcut.
1pecifying 'etLe#e-9()(1) is the e-uivalent of specifying 'etLe#e-9().'etRow(1).
Returns
This function returns a rowset ob8ect that references the base rowset. For a component, this is
the level / of the page. For a 3eople1oft %pplication 2ngine program, this is the state record
rowset. For a message, this is the base rowset.
Note. >ou can also get the base rowset for a message using the Cet&owset message class
method, that is, &(&'.'etRow8et().
Example
The following code sample returns the level one rowset.
Lo!,- Row8et &R$6&ET;
&R$6&ET = 'etLe#e-9().'etRow(1).'etRow8et(&CR$LL.LEVEL1_REC);
The following is e-uivalent to the previous eample.
Lo!,- Row8et &R$6&ET;
&R$6&ET = 'etLe#e-9()(1).'etRow8et(&CR$LL.LEVEL1_REC);
To reference a level H rowset you would have code similar to this:
Lo!,- Row8et &R$6&ET_LEVEL, &R$6&ET_LEVEL9, &R$6&ET_LEVEL1;
&R$6&ET_LEVEL = 'etLe#e-9().'etRow(1).'etRow8et(&CR$LL.LEVEL1_REC).'etRow(R).
'etRow8et(&CR$LL.LEVEL_REC);
F3 or 3F
&R$6&ET_LEVEL9 = 'etLe#e-9();
&R$6&ET_LEVEL1 = &R$6&ET_LEVEL9.'etRow(1).'etRow8et(&CR$LL.LEVEL1_REC);
&R$6&ET_LEVEL = &R$6&ET_LEVEL1.'etRow(R).'etRow8et(&CR$LL.LEVEL_REC);
F3 or 3F
&R$6&ET_LEVEL = 'etLe#e-9()(1).LEVEL1_REC(R).'etRow8et(&CR$LL.LEVEL_REC);
See Also
*etRecor
Syntax
#etRecord([RECORD.recname])
Description
Use the Cet&ecord function to create a reference to a record ob8ect for the current contet, that
is, from the row containing the currently eecuting program.
The following code:
&REC = 'etRe!or/();
is e-uivalent to:
&REC = 'etRow().'etRe!or/(Re!or/.re!n,me);
or
&REC = 'etRow().re!n,me;
Note. This function is invalid for 3eople'ode programs located in events that aren5t associated
with a specific row and record at the point of eecution. That is, you cannot use this function in
3eople'ode programs on events associated with high)level ob8ects like pages (the Activate
event* or components (component events*.
&arameters
$ith no parameters, this function returns a record ob8ect for the current contet (the record
containing the program that is running*.
+f a parameter is given, RECORD. recname must specify a record in the current row.
Returns
Cet&ecord returns a record ob8ect.
Example
+n the following eample, the level H rowset (scroll* has two records: 2437A':F71TA+T4, (the
primary record* and ':F71TA+T4AT07. +f the code is running from a field on the
2437A':F71TA+T4 record, the following returns a reference to that record:
&REC = 'etRe!or/(); F3return8 Gr"m,r< re!or/ 3F
The following returns the other record in the current row.
&REC = 'etRe!or/(REC$R%.C)IL&T_IT(_T1L);
The following event uses the I symbol to convert a record name thats been passed in as a
string to a component name.
*un!t"on 8et_8ub_e#ent_"n.o(&REC A8 Re!or/, &NA(E A8 8tr"n7)
&*LA'& = Cre,teRe!or/(REC$R%.%R_LINE_*L'_&1R);
&REC.CoG<*"e-/8To(&*LA'&);
&IN*$ = #etRecord(M(:REC$R%.: N &NA(E));
I. A--(&IN*$) T+en
&*LA'&.CoG<*"e-/8To(&IN*$);
En/0I.;
En/0*un!t"on;
*etRow
Syntax
#etRow()
Description
Use the Cet&ow function to obtain a row ob8ect for the current contet, that is the row containing
the currently eecuting program.
Using the Cet&ow function is e-uivalent to:
&R$6 = 'etRow8et().'etRow(CurrentRowNumber());
Note. For 3eople'ode programs located in events that are not associated with a specific row at
the point of eecution, this function is invalid. That is, you cannot use this function in 3eople'ode
programs on events associated with high)level ob8ects like pages or components.
&arameters
,one.
Returns
Cet&ow returns a row ob8ect that references the current row in the component buffers. +f the
program is not being run from a page (such as from 3eople1oft %pplication 2ngine, or as part of
a 4essage program* it references that data.
Example
Lo!,- Row &R$6;
&R$6 = 'etRow();
*etRowset
Syntax
#etRowset([(CRO--.scrollname])
Description
Use the Cet&owset function to get a rowset ob8ect based on the current contet. That is, the
rowset is determined from the row containing the program that is running.
Syntax Format Consierations
%n epression of the form
REC$R%.8!ro--n,me.GroGert<
or
REC$R%.8!ro--n,me.met+o/(. . .)
is converted to an ob8ect epression by using Cet&owset(SCROLL. scrollname*.
&arameters
+f a parameter is specified, it must be the name of the primary record for the scroll that is a child
of the current contet.
Returns
$ith no parameters, Cet&owset returns a rowset ob8ect for the rowset containing the currently
running program. +f a parameter is specified, it returns a rowset for that child scroll. scrollname
must be the name of the primary record for the scroll.
Example
+n the following eample, &1@ is a level @ rowset, and &1H is a child rowset of &1@.
Lo!,- Row8et &R&1, &R&;
&R&1 = 'etRow8et();
&R& = 'etRow8et(&CR$LL.E(@L_C)IL&T_IT();
*lo(al
Syntax
#loal data_type &var_name
Description
Use the Clobal statement to declare 3eople'ode global variables. % global variable, once
declared in any 3eople'ode program, remains in scope throughout the 3eople1oft session. The
variable must be declared with the Clobal statement in any 3eople'ode program in which it is
used.
;eclarations tend to appear at the beginning of the program, intermied with function
declarations.
,ot all 3eople'ode data types can be declared as Clobal. For eample, %pi<b8ect data types can
only be declared as 7ocal.
&arameters
dataAtype 1pecify a 3eople'ode data type.
&var_name % legal variable name.
Example
The following eample declares a global variable and then assigns it the value of a field:
7-ob,- 8tr"n7 &AE_A@@L_I%;
&AE_A@@L_I% = AE_A@@L_I%;
*ray
Syntax
#ray(scrollpath, target_row, [recordname.]fieldname)
where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]]
RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL. scrollname, where scrollname is
the same as the scroll levels primary record name.
+f you put the function on the same scroll level as the field being changed, you can use the
following synta:
#ray(&ieldname)
The more comple synta can be used to loop through a scroll on a lower level than the
3eople'ode program.
Description
Use the Cray function to make a field unavailable for entry a page field, preventing the user from
making changes to the field.
Note. This function remains for backward compatibility only. Use the 2nabled field class property
instead.
Cray makes a field display)only, while :ide makes it invisible. >ou can undo these effects using
the built)in functions Ungray and Unhide.
Note. +f you specify a field as ;isplay <nly in 3eople1oft %pplication ;esigner, using the
3eople'ode functions Cray, followed by Ungray, will not make it editable. This function shouldn5t
be used in any event prior to &ow+nit.
This eample, which would typically be found in the &ow+nit event, disables the pages address
fields if the value of the 1%42A%;;&211A2437 field is ?>?.
I. &A(E_A%%RE&&_E(@L = :4: T+en
'r,<(&TREET1);
'r,<(&TREET);
'r,<(CIT4);
'r,<(&TATE);
'r,<(SI@);
'r,<(C$UNTR4);
'r,<()$(E_@)$NE);
En/0".;
,ie
Syntax
/ide(scrollpath, target_row, [recordname.]fieldname)
where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]]
RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL.scrollname, where scrollname is
the same as the scroll levels primary record name.
Description
Use the :ide function to make a page field invisible.
Note. This function remains for backward compatibility only. Use the Visible field class property
instead.
>ou can display the field again using Unhide, but Unhide has no effect on a field that has been
made display)only in the page definition.
Cray, :ide, Ungray, and Unhide usually appear in &ow+nit programs that set up the initial display
of data, and in Field'hange programs that change field display based on changes the user
makes to a field. Cenerally, you put the functions on the same scroll level as the field that is being
changed. This reduces the compleity of the functions synta to:
/ide(."e-/n,me)
The more comple synta can be used to loop through a scroll on a lower level than the
3eople'ode program.
Note. This function shouldn5t be used in any event prior to &ow+nit.
Example
This eample hides the pages address fields if 1%42A%;;&211A2437 is e-ual to ?>?:
I. &A(E_A%%RE&&_E(@L = :4: T+en
)"/e(&TREET1);
)"/e(&TREET);
)"/e(CIT4);
)"/e(&TATE);
)"/e(C$UNTR4);
)"/e()$(E_@)$NE);
En/0".;
's%*et
Syntax
"s)#et(message_set, message_num, default_msg_txt [, paramlist])
where paramlist is an arbitrary)length list of parameters of undetermined (%ny* data type to be
substituted in the resulting tet string, in the form:
param1 [, param2]. . .
Description
Use the 4sgCet function to retrieve a message from the 3eople'ode 4essage 'atalog and
substitutes in the values of the parameters into the tet message.
>ou can access and update the 4essage 'atalog through the 3eopleTools Utilities, using the
4essage 'atalog page located under the Use menu. >ou can enter message tet in multiple
languages. The 4essage 'atalog also enables you to enter more detailed ?2plain? tet about
the message. The message_set and message_num parameters specify the message to retrieve
from the catalog. +f the message is not found in the 4essage 'atalog, the default message
provided in default_msg_txt is used. 4essage sets @ through @J,JJJ are reserved for use by
3eople1oft applications. 4essage sets H/,/// through KH,LML can be used by 3eople1oft users.
The optional paramlist is a comma)separated list of parameters! the number of parameters in the
list is arbitrary. The parameters are referenced in the message tet using the N character
followed by an integer corresponding to the position of the parameter in the paramlist. For
eample, if the first and second parameters in paramlist were BF+27;,%42 and BU12&,%42,
they would be inserted into the message string as N@ and NH. To include a literal percent sign in
the string, use NN! NO is used to indicate an end)of)string and terminates the string at that point.
This is generally used to specify fied)length strings with trailing blanks.
4sgCet suffies the message with ?"4essage 1etP and 4essage 2rrorP#?, so it can be processed
by a user not conversant in the translated language.
Example
&(87Te;t = (87'et(K9999, , :(e88,7e not .oun/:);
's%*et-ext
Syntax
"s)#et'e0t(message_set, message_num, default_msg_txt [, paramlist])
where paramlist is an arbitrary)length list of parameters of undetermined (%ny* data type to be
substituted in the resulting tet string, in the form:
param1 [, param2]. . .
Description
Use the 4sgCetTet function to retrieve a message from the 3eople'ode 4essage 'atalog and
substitutes the values of the parameters in paramlist into the tet message. +t returns the resulting
message tet as a 1tring data type.
>ou can access and update the 4essage 'atalog through the 3eopleTools Utilities window,
using the 4essage 'atalog page located under the Use menu. >ou can enter message tet in
multiple languages. The message_set and message_num parameters specify the message to
retrieve from the catalog. +f the message is not found in the 4essage 'atalog, the default
message provided in default_msg_txt is used. 4essage sets @ through @J,JJJ are reserved for
use by 3eople1oft applications. 4essage sets H/,/// through KH,LML can be used by 3eople1oft
users.
The parameters listed in the optional paramlist are referenced in the message tet using the N
character followed by an integer referencing the position of the parameter in the function call. For
eample, if the first and second parameters in paramlist were BF+27;,%42 and BU12&,%42,
they would be inserted into the message string as N@ and NH. To include a literal percent sign in
the string, use NN! NO is used to indicate an end)of)string and terminates the string at that point.
This is generally used to specify fied)length strings with trailing blanks.
Unlike the 4sgCet function, 4sgCetTet returns the message without a message set and
message number appended to the message.
Example
&(87Te;t = (87'etTe;t(K9999, , :(e88,7e not .oun/:);
SetDe#ault
Syntax
(etDe+ault([recordname.]fieldname)
Description
Use the 1et;efault function to set a field to a null value, so that the net time default processing
occurs, it is set to its default value: either a default specified in its record field definition or one set
programmatically by 3eople'ode located in a Field;efault event. +f neither of these defaults eist,
the 'omponent 3rocessor leaves the field blank.
Note. This function remains for backward compatibility only. Use the 1et;efault field class
property instead.
0lank numbers correspond to .ero on the database. 0lank characters correspond to a space on
the database. 0lank dates and long characters correspond to ,U77 on the database. 1et;efault
gives each field data type its proper value.
1ee 1et;efault.
!here to $se SetDe#ault
+f a 3eople'ode program or function eecutes the 1et;efault built)in on a field that does not eist
in the component buffer, the remainder of the program or function is skipped. +n the case of a
function, eecution of the calling program continues with the net statement after the call to the
function. :owever, if the program containing the 1et;efault call is at the ?top level?, meaning that
it was called directly from the component processor or application engine runtime, it eits.
Therefore, if you want to control the behavior of 1et;efault, you should encapsulate any calls to
this built)in function inside your own functions. This enables your overall programs to continue,
whether or not the 1et;efault succeeds.
&arameters
[recordname.fieldname 1pecify a field designating the fields that you want to set to its default
value.
Returns
<ptionally returns a 0oolean value indicating whether the function eecuted successfully.
Example
This eample resets the 3&<V+;2& to its null value. This field is reset to its default value when
default processing is net performed:
I. C$VERA'E_ELECT = :6: T+en
&et%e.,u-t(@R$VI%ER);
En/0".;
S.LExec
Syntax
(1-E0ec(Ts'lcmd N (1-.s'lnameU, bindexprs, outputvars)
where bindexprs is a list of epressions, one for each !n reference within s"lcmd or the tet found
in the 167 defintion s"lname, in the form:
inexpr_1 [, inexpr_2]. . .
and where outputvars is a list of variables, record fields, or record ob8ect references, one for each
column selected by the 167 command, in the form:
out_1 [, out_2]. . .
Description
Use the 1672ec function to eecute a 167 command from within a 3eople'ode program by
passing a 167 command string. The 167 command bypasses the 'omponent 3rocessor and
interacts with the database server directly. +f you want to delete, insert, or update a single record,
use the corresponding 3eople'ode record ob8ect method.
+f you want to delete, insert, or update a series of records, all of the same type, use the
'reate167 or Cet167 functions, then the 2ecute 167 class method.
Limitation o# S.LExec SELEC- Statement
1672ec can only 1elect a single row of data. +f your 167 statement (or your S.L.s"lname
statement* retrieves more than one row of data, 1672ec sends only the first row to its output
variables. %ny subse-uent rows are discarded. This means if you want to fetch only a single row,
1672ec can perform better than the other 167 functions, because only a single row is fetched.
+f you need to 1272'T multiple rows of data, use the 'reate167 or Cet167 functions and the
Fetch 167 class method. >ou can also use 1croll1elect or one of the 1elect methods on a
rowset ob8ect to read rows into a (usually hidden* work scroll.
Note. The 3eople1oft record name specified in the 167 1272'T statement must be in
uppercase.
Limitations o# S.LExec $&DA-E/ DELE-E/ an )NSER- Statements
S.LExec statements that result in a database update (specifically, U3;%T2, +,12&T, and
;272T2* can only be issued in the following events:
1ave3re'hange
$orkFlow
1ave3ost'hange
Field'hange
&emember that 1672ec U3;%T2s, +,12&Ts, and ;272T2s go directly to the database server,
not to the 'omponent 3rocessor (although 1672ec can look at data in the buffer using bind
variables included in the 167 string*. +f a 1672ec assumes that the database has been updated
based on changes made in the component, that 1672ec can be issued only in the
1ave3ost'hange event, because before 1ave3ost'hange none of the changes made to page
data has actually been written back to the database.
Strin%
Syntax
(trin)(value)
Description
Use the 1tring to convert any non)string data type (ecept <b8ect* to a string.
,ormally the 'omponent 3rocessor automatically handles data type conversions. :owever, for
some operations, such as comparisons, you want to specify the data type eplicitly. %ssume, for
eample, that you have two fields F+27;A+ and F+27;A9 containing number values Q/// and
@////. %s character fields, @//// is less than Q/// (because the first character in @//// is less
than the first character in Q///*. %s numbers, however, @//// is of course greater than Q///.
Note. ;ue to the internal representation of numbers, sometimes 1tring represents numbers
differently. +f you want to control eactly how a number is represented, use the ,umberTo1tring
function.
&arameters
value % value of any type other than ob8ect, to be converted to its 1tring representation.
Returns
&eturns a 1tring value representing value.
Example
To force the comparison of the two fields as strings, you could use:
". 8tr"n7(*IEL%_1) B 8tr"n7(*IEL%_). . .
>ou can use the 1tring function with a field ob8ect as follows:
&%ATE = 'etRe!or/(REC$R%.%ERIVE%_)R).'et*"e-/(*IEL%.E**%T);
&&TR = &tr"n7(&%ATE.V,-ue);
-rans#er
Syntax
'rans+er(new_instance,
"EN$NA"E.menuname,
%ARNA"E.barname,
&'E"NA"E.menu_itemname,
!A#E.component_item_name,
action [, eylist] [, (utoSearch]);
where keylist is a list of field references in the form:
[recordname.]field1 [, [recordname.]field2]. . .
<&
!"ecord#b$ect1 [, !"ecord#b$ect2]. . .
Description
Use the Transfer function to close the current page and transfers the end)user to another page,
either within the current component or in another component. Transfer can either start a new
instance of the application and transfer to the new page there, or close the old page and transfer
to the new one in the same instance of 3eopleTools.
Note. The Transfer function cannot be used with an internet script or an application engine
program.
Transfer is more powerful than the simpler Transfer3age, which permits a transfer only within the
current component in the current instance of 3eopleTools. :owever, any variables declared as
'omponent do not remain defined after using the Transfer function, whether youre transferring
within the same component or not.
>ou can use Transfer from a secondary page (either with or without using a pop)up menu* only if
youre transferring to a separate instance of a component. >ou cannot use Transfer from a
secondary page if youre not transferring to a separate instance of a component.
+f you provide a valid search key for the new page in the optional keylist, the new page opens
directly, using the values provided from keylist as search key values. % valid key means that
enough information is provided to uni-uely identify a row: not all of the key values need to be
provided. +f no key is provided, or if the key is invalid, or if not enough information is provided to
identify a uni-ue row, the search dialog bo displays, enabling the end user to search for a row.
Note. +f Force 1earch 3rocessing is specified in 3eople1oft %pplication ;esigner for the
component, the search dialog bo always displays, whether the keylist is provided or not.
+f barnameRitemnameRcomponent_item_name is an invalid combination, an error message
displays eplaining that there were invalid transfer parameters.
+n the component_item_name parameter, make sure to pass the component item name for the
page, not the page name. The component item name is specified in the component definition, in
the +tem ,ame column on the row corresponding to the specific page, as shown here:
'omponent +tem ,ame
Di##erences 0etween -rans#er an -rans#erExact
$hen you do a transfer, the first thing the system checks is whether all the key field values for the
target component are provided.
+f all the keys aren5t provided, the search page is displayed. +n this scenerio, Transfer2act and
Transfer are the same.
+f all the keys are provided, a 1elect is done against the search record for that component using
those keys.
+f you use the Transfer function, a 7+F2 operator is used in the $here clause of that
1elect for each key.
+f you use the Transfer2act fuction, the e-uals operator is used in the $here clause for
each key. Using e-uals allows the database to take full advantage of key indees for
maimum performance.
1ee Transfer2act.
Restrictions on $se !ith a Component )nter#ace
This function is ignored (has no effect* when used by a 3eople'ode program thats been called
by a 'omponent +nterface.
Restrictions on $se !ith Search)nit Event
>ou can5t use this function in a 1earch+nit 3eople'ode program.
Consierations $sin% Exceptions an the -rans#er Function
Using the Transfer function, inside a try block, to transfer a user to a page in another component,
does not catch 3eople'ode eceptions thrown in the new component. 1tarting a new component
starts a brand new 3eople'ode evaluation contet. 'atches are only caught for eceptions
thrown within the current component.
+n the following code eample, the catch statement only catches eceptions thrown in the code
prior to using the ;o4odal function, but not any eceptions that are thrown within the new
component.
F3 &et uG tr,n8,!t"on 3F
I. >ComGInt.!N,me = :: T+en
tr<
&oTr,n8 =
&7_ER(&_Tr,n8,!t"onCo--e!t"on.'etTr,n8,!t"on1<N,me(R1_E(_6RI.%E&CR);
&8&e,r!+@,7e = &oTr,n8.&e,r!+@,7e;
&8&e,r!+Re!or/ = &oTr,n8.&e,r!+Re!or/;
&8&e,r!+T"t-e = &oTr,n8.'et&e,r!+@,7eT"t-e();
I. Not A--(&8&e,r!+@,7e, &8&e,r!+Re!or/, &8&e,r!+T"t-e) T+en
Error ((87'etTe;t(1J2KL, 2921, :(e88,7e Not *oun/:));
En/0I.;
&!_ER(&_&e,r!+Tr,n8,!t"on = &oTr,n8;

F3 AttemGt to tr,n8.er to +"//en 8e,r!+ G,7e w"t+ !on."7ur,b-e ."-ter 3F
&n(o/,-Return = Do"odal(M(:@,7e.: N &8&e,r!+@,7e), &8&e,r!+T"t-e, 0 1, 0
1);
!,t!+ E;!eGt"on &e
Error ((87'etTe;t(1J2KL, 292, :(e88,7e Not *oun/:));
en/0tr<;
-rans#er&a%e
Syntax
'rans+er!a)e([!A#E.page_name_n,me])
Description
Use the Transfer3age function to transfer control to the page indicated by &A*E.
page__namename within, or to the page set with the 1et,et3age function. The page that you
transfer to must be in the current component or menu. To transfer to a page outside the current
component or menu, or to start a separate instance of 3eopleTools prior to transfer into, use the
Transfer function.
1ee 1et,et3age, Transfer.
Note. >ou cant use Transfer3age from a secondary page.
%ny variable declared as a 'omponent variable will still be defined after using a Transfer3age
function.
Consierations $sin% -rans#er&a%e
The following are important considerations when using the Transfer3age function:
Transfer3age always terminates the current 3eople'ode program.
Transfer3age is always processed after all events are completed.
Civen these considerations, here are some scenarios for how Transfer3age eecutes:
$hen called in &ow+nit: The current &ow+nit 3eople'ode program is terminated, but
&ow+nit processing continues. +n addition, &ow+nit 3eople'ode programs run for the rest
of the fields in the row. Then Transfer3age is processed.
$hen called in Field2dit: The Field2dit 3eople'ode program is terminated. The
Field'hange program for that field still runs. Then Transfer3age is processed.
$hen called in 1ave3re'hange: The 1ave3re'hange program for that field is
terminated. 1ave3re'hange runs for the rest of the fields on that page. Then
1ave3ost'hange run for all the fields. Then Transfer3age is processed.
$hen called in Field'hange in deferred mode: +n deferred mode, changed fields are
processed in order. The Field'hange program is terminated. Then any subse-uent fields
in the page order are processed with the normal Field2dit)Field 'hange logic. <nce that
has finished, the Transfer3age is processed.
$hen Transfer3age is processed, any 3eople'ode associated with the %ctivate event for the
page being transferred to runs. This always occurs at the end, after all field processing.
+f Transfer3age is called multiple times during field processing, all the calls are processed at the
end, in the same order the calls were made. The %ctivate event eecutes each time. The final
active page is the one that was transferred to by the last call.
Restrictions on $se !ith a Component )nter#ace
This function is ignored (has no effect* when used by a 3eople'ode program thats been called
by a 'omponent +nterface.
Restrictions on $se !ith Search)nit Event
>ou can5t use this function in a 1earch+nit 3eople'ode program.
&arameters
page_name % 1tring e-ual to the name of the page you are transferring to, as set in the page
definition, prefied with the reserved word &a%e. The page must be in the same
component as the page you are transferring from.
Returns
<ptionally returns a 0oolean value indicating whether the function eecuted successfully.
Example
The following eamples both perform the same function, which is to transfer to the 9<0A;%T%AS
page:
Tr,n8.er@,7e(@A'E.V$1_%ATA_L);
or
&etNe;t@,7e(@A'E.V$1_%ATA_L);
Tr,n8.er@,7e( );
-rans#erExact
Syntax
'rans+erE0act(new_instance,
"EN$NA"E.menuname,
%ARNA"E.barname,
&'E"NA"E.menu_itemname,
!A#E.component_item_name,
action [, eylist] [, (utoSearch]);
where keylist is a list of field references in the form:
[recordname.]field1 [, [recordname.]field2]. . .
<&
!"ecord#b$ect1 [, !"ecord#b$ect2]. . .
Description
Use the Transfer2act function to close the current page and transfers the user to another page,
either within the current component or in another component. Transfer2act can either start a
new instance of the application and transfer to the new page there, or close the old page and
transfer to the new one in the same instance of 3eopleTools.
Note. The Transfer2act function cannot be used with an internet script or an application engine
program.
Transfer2act is more powerful than the simpler Transfer3age, which permits a transfer only
within the current component in the current instance of 3eopleTools. :owever, any variables
declared as 'omponent do not remain defined after using the Transfer2act function, whether
youre transferring within the same component or not.
>ou can use Transfer2act from a secondary page (either with or without using a pop)up menu*
only if youre transferring to a separate instance of a component. >ou cannot use Transfer2act
from a secondary page if youre not transferring to a separate instance of a component.
+f you provide a valid search key for the new page in the optional keylist, the new page opens
directly, using the values provided from keylist as search key values. % valid key means that
enough information is provided to uni-uely identify a row: not all of the key values need to be
provided. +f no key is provided, or if the key is invalid, or if not enough information is provided to
identify a uni-ue row, the search dialog bo displays, enabling the end user to search for a row.
Note. +f Force 1earch 3rocessing is specified in 3eople1oft %pplication ;esigner for the
component, the search dialog bo always displays, whether the keylist is provided or not.
+f barnameRitemnameRcomponent_item_name is an invalid combination, an error message
displays eplaining that there were invalid transfer parameters.
+n the component_item_name parameter, make sure to pass the component item name for the
page, not the page name. The component item name is specified in the component definition, in
the +tem ,ame column on the row corresponding to the specific page, as shown here:
'omponent +tem ,ame
Di##erences 0etween -rans#er an -rans#erExact
$hen you do a transfer, the first thing the system checks is whether all the key field values for the
target component are provided.
+f all the keys aren5t provided, the search page is displayed. +n this scenario, Transfer2act and
Transfer are the same.
+f all the keys are provided, a 1elect is done against the search record for that component using
those keys.
+f you use the Transfer function, a 7+F2 operator is used in the $here clause of that
1elect for each key.
+f you use the Transfer2act fuction, the e-uals operator is used in the $here clause for
each key. Using e-uals allows the database to take full advantage of key indees for
maimum performance.
1ee Transfer.
Restrictions on $se !ith a Component )nter#ace
This function is ignored (has no effect* when used by a 3eople'ode program thats been called
by a 'omponent +nterface.
Restrictions on $se !ith Search)nit Event
>ou can5t use this function in a 1earch+nit 3eople'ode program.
Consierations $sin% Exceptions an the -rans#erExact Function
Using the Transfer2act function inside a try block to transfer a user to a page in another
component does not catch 3eople'ode eceptions thrown in the new component. 1tarting a new
component starts a brand new 3eople'ode evaluation contet. 'atches are only caught for
eceptions thrown within the current component.
+n the following code eample, the catch statement only catches eceptions thrown in the code
prior to using the ;o4odal function, but not any eceptions that are thrown within the new
component.
F3 &et uG tr,n8,!t"on 3F
I. >ComGInt.!N,me = :: T+en
tr<
&oTr,n8 =
&7_ER(&_Tr,n8,!t"onCo--e!t"on.'etTr,n8,!t"on1<N,me(R1_E(_6RI.%E&CR);
&8&e,r!+@,7e = &oTr,n8.&e,r!+@,7e;
&8&e,r!+Re!or/ = &oTr,n8.&e,r!+Re!or/;
&8&e,r!+T"t-e = &oTr,n8.'et&e,r!+@,7eT"t-e();
I. Not A--(&8&e,r!+@,7e, &8&e,r!+Re!or/, &8&e,r!+T"t-e) T+en
Error ((87'etTe;t(1J2KL, 2921, :(e88,7e Not *oun/:));
En/0I.;
&!_ER(&_&e,r!+Tr,n8,!t"on = &oTr,n8;

F3 AttemGt to tr,n8.er to +"//en 8e,r!+ G,7e w"t+ !on."7ur,b-e ."-ter 3F
&n(o/,-Return = Do"odal(M(:@,7e.: N &8&e,r!+@,7e), &8&e,r!+T"t-e, 0 1, 0
1);
!,t!+ E;!eGt"on &e
Error ((87'etTe;t(1J2KL, 292, :(e88,7e Not *oun/:));
en/0tr<;
See Also
Transfer3age.
'reating 4enu ;efinitions
'reating 'omponent ;efinitions
&arameters
new_instance 1et this parameter to True to start a new application instance, or to False
to use the current window and replace the page already displayed.
#enuname The name of the menu where the page is located prefied with the
reserved word 'EN$NA'E.
$arname The name of the menu bar where the page is located, prefied with the
reserved word 0ARNA'E.
menu_itemname The name of the menu item where the page is located, prefied with the
reserved word )-E'NA'E.
component_item_name The component item name of the page to be displayed on top of the
component when it displays. The component item name is specified in
the component definition. This parameter must be prefied with the
keyword &A*E.
Action Uses a single)character code as in N%ction. Valid actions are ?%? ( add*,
?U? (update*, ?7? (updateGdisplay all*, ?'? (correction*, and ?2? (data
entry*.
%eylist %n optional list of field specifications used to select a uni-ue row at level
.ero in the page you are transferring to, by matching keys in the page you
are transferring from. +t can also be an already instantiated record ob8ect.
+f a record ob8ect is specified, any field of that record ob8ect that is also a
field of the search record for the destination component is added to
keylist. The keys in the fieldlist must uni-uely identify a row in the ?to?
page search record. +f a uni-ue row is not identified, or if Force 1earch
3rocessing is selected for the component, the search dialog bo appears.
+f the keylist parameter is not supplied then the destination component5s
search key must be found as part of the source components level /
record buffer.
Auto&earch 1pecify whether an automatic search on the target search page is
eecuted after the transfer. This means the search results are already
shown without the end)user having to click the 1earch button. This
parameter takes a 0oolean value: True, do an automatic search. The
default value is False (that is, the user has to click the 1earch button*.
Returns
,one.
Example
The eample starts a new instance of 3eopleTools and transfers to a new page in Update mode.
The data in the new page is selected by matching the 2437+; field from the old page.
Tr,n8.erE;,!t(true, (ENUNA(E.A%(INI&TER_@ER&$NNEL, 1ARNA(E.U&E,
ITE(NA(E.@ER&$NAL_%ATA, @A'E.@ER&$NAL_%ATA_1, :U:);
Using the following 3eople'ode program:
&(4REC = Cre,teRe!or/(REC$R%.=E$@C_DA*IEL%&);
&(4REC.=E_TITLE.V,-ue = :IE4:;
'rans+er(*,-8e, (enuN,me.=E_@E$@LEC$%E_@A'E&, 1,rN,me.U&E,
ItemN,me.=E@CD@R$@&TE&T&, @,7e.=E$@C_DA*IEL%&, :U:, &(4REC);
The following 167 is produced:
&ELECT %I&TINCT T$@ K91 =E_TITLE, =E@C_ALT&RC) *R$( @&_=E$@C_DA*IEL%&
6)ERE =E_TITLE LIIE CIE4>C $R%ER 14 =E_TITLE
+f you change the Transfer to Transfer2act:
&(4REC = Cre,teRe!or/(REC$R%.=E$@C_DA*IEL%&);
&(4REC.=E_TITLE.V,-ue = :IE4:;
'rans+erE0act(*,-8e, (enuN,me.=E_@E$@LEC$%E_@A'E&, 1,rN,me.U&E,
ItemN,me.=E@CD@R$@&TE&T&, @,7e.=E$@C_DA*IEL%&, :U:, &(4REC);
The following 167 is produced:
&ELECT %I&TINCT T$@ K91 =E_TITLE, =E@C_ALT&RC) *R$( @&_=E$@C_DA*IEL%&
6)ERE =E_TITLE=?1 $R%ER 14 =E_TITLE