GetNextNumber function

Syntax

GetNextNumber({record.field | record_name, field_name}, max_number)

Description

Use the GetNextNumber function to increment the value in a record for the field you specify by one and returns that value. You might use this function to increment an employee ID field by one when you are adding a new employee. If the new value generated exceeds max_number, a negative value is returned and the field value isn't incremented.

The maximum value possible for max_number is 2147483647.

Parameters

Parameter	Description
record.field	Specify the record and field identifiers for the field for which you want the new number. This is the recommended way to identify the field.
record_name	Specify as a string the name of the record containing the field for which you want the new number. This parameter with field_name was used prior to PeopleTools 8.
field_name	Specify as a string the name of the field for which you want the new number. This parameter with record_name was used prior to PeopleTools 8. Note: If you use the older syntax (record_name, field_name), you have to manually update these two parameters in your programs whenever that record or field is renamed. The new syntax (record.field) is automatically updated, so you won't have to maintain it.
max_number	Specify the highest allowed value for the field you're incrementing. The maximum value possible for max_number is 2147483647.

Returns

A Number value equal to the highest value of the field specified plus one.

GetNextNumber returns an error if the value to be returned would be greater than max_number. The function returns one of the following:

Numeric Value	Constant Value	Description
Number	N/A	The new number
-1	%GetNextNumber_SQLFailure	SQL failure
-2	%GetNextNumber_TooBig	Number too large, beyond max_number
-3	%GetNextNumber_NotFound	No number found, invalid data format

Example

If %Component = "RUN_AR33000" Then 
   DUN_ID_NUM = GetNextNumber(INSTALLATION_AR.DUN_ID_NUM, 99999999); 
End-if;

The following uses the constant to check for the value returned:

&VALUE = GetNextNumber(INSTALLATION_AR.DUN_ID_NUM, 999); 
Evaluate &VALUE 
When = %GetNextNumber_SQLFailure 
     /* do processing */ 
When = %GetNextNumber_TooBig 
     /* do processing */ 
When = %GetNextNumber_NotFound 
     /* Do processing */ 
When-other 
     /* do other processing */ 
End-Evaluate;

PeopleCode Event Considerations

Because this function results in a database update (specifically, UPDATE, INSERT, and DELETE) it should only be issued in the following events:

• SavePreChange

• WorkFlow

• SavePostChange

If you use this function in an event other than these, you need to ensure that the dataflow is correct and that you do not receive unexpected results.

GetNextNumber and GetNextNumberWithGapsCommit

The following is some of the differences between the two functions, to enable you to better chose which one is better for your application.

GetNextNumber	GetNextNumberWithGapsCommit
No AutoCommit (which can be a problem, as the table is locked until all Save events are finished.)	AutoCommit (this can be a performance enhancement as table is not locked as long).
	Ability to use WHERE criteria for maintaining multiple sequence numbers in a single record.
	Ability to increment by more than 1.
Allowed in SavePostChange	Can be used in any PeopleCode event.