Cols.val()

note

This article is about the val() function of the Cols object.

Cols.val()

Gets or sets the value of the first column in scope, with its IO format applied.

tip

To get or set the raw, unformatted value instead, use .rawVal().

Returns a string representing the current value of the first column in scope if value is omitted. Returns the this object if value is specified.

Syntax

$.udb( *ds* ).rows( *rowRef1*, [rowRef2] ).cols( [columns] ).val( [value], [lookupRef] )
$.udb( *ds* ).rowSet( *rowSet* ).rows( *rowRef1*, [rowRef2] ).cols( [columns] ).val( [value], [lookupRef] )

$.udb( *ds* ).rows( *rowRef1*, [rowRef2] ).cols( [columns] ).val( [value], [quiet] )

$.udb( *ds* ).searchCols( [columns] ).val( [value], [lookupRef] )

*quiet*  ::= { true | [false] }

The required ds parameter is a data source selector.

The optional rowSet parameter is a rowset identifier. If the .rowSet() clause is omitted, then .rowSet('current') is assumed.

The required rowRef1, and optional rowRef2, are row selectors. Unlike the column meta-information functions, reading or writing an actual value requires a specific record to be identified. If ommitted, then .rows('current') is assumed.

The optional columns is a column selector. If omitted, all columns in scope are selected.

The optional value is a new value that the first column in scope is set to.

The optional lookup-ref is an object used to specify additional information about the value, in the situation where an autocompletion control is used, and the value refers to a column in its associated data source.

The optional quiet is a boolean used to specify if the new value must also be propagated immediately to all controls that may show it. If quiet is false (the default), it is immediately shown after the value is successfully changed.

note

Whatever value .val() reads or writes, regular column or search column alike, is always formatted (and, when writing, parsed) according to the column's IO format — see $.udb.ioFormat. Unformatted 'raw' values are handled by the .rawVal() function.

.searchCols() columns are different from regular columns in what their value is used for: instead of being a record's actual value, it becomes part of the WHERE clause the next time .executeQuery() is called on that data source. Because of this, .searchCols().val() additionally accepts USoft's search-expression syntax as a value, on top of the column's regular IO format — comparison operators (=, <, >, <=, >=, <>), | (OR) and & (AND) to combine conditions, ! to negate, the wildcards %/_, and NULL. See the search parameter for the full syntax.

Examples

let empNo = $.udb('EMP').rows('current').cols('EMPNO').val();

$.udb('EMP').rows('current').cols('DEPT').val('INT');

Setting a search condition with a plain value behaves just like setting a regular value:

$.udb('EMP').searchCols('DEPT').val('SALES');

Setting a search condition with an expression instead, to find employees hired since the start of 2024:

$.udb('EMP').searchCols('HIREDATE').val('>=01-01-2024');

Related events

The following events are only triggered when value is specified, since only then is a value actually written.

Event	Applies to	Occurs when
rowpreupdate	Data source objects	Before a record is updated
colpreupdate	Data source objects	Before a value in a column is updated
colpostupdate	Data source objects	After a value in a record is updated
rowpostupdate	Data source objects	After a record is updated