9.75 FORMAT_STRING

Note: Built-In Function Rules Usage Options

This Built-in Function returns a character string which is built from an input Format Pattern. The Format Pattern can consist of text plus field values. Editing options may be applied to the field values.

Special Note: All characters preceded by a colon (:) will be treated as a field name and ends with either one of the following characters () space and colon.

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Format Pattern

Refer to Technical Notes for pattern syntax and options.

Fields specified as :field

Optional formatting options may be appended to fields. The option/s immediately follow the field name and are enclosed in brackets ().

(editcode,x) apply edit code to field value where x is a valid LANSA editcode. Refer to Standard Field Edit Codes for a list of valid edit codes.

(substr,n1,n2) apply substring to field value where n1=start position, n2=length.
(triml) remove leading blanks from field value.
(trim) remove trailing blanks from field value.
(trimall) remove leading and trailing blanks from field value.
(upper) convert field value to uppercase.
(lower) convert field value to lowercase.

1

Unlimited

2

A

Opt

DBCS enable

Default: disable

YES = to enable

Note: For substring, the number count is for each character, not byte.

3

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Formatted String

1

unlimited

2

A

Opt

Return code

OK = action completed

ER = Error occurred

2

Technical Notes

Field names are preceded by a colon (:).
Example Format Pattern =
Employee :givename :surname with number :EMPNO was not found.

Return Formatted String =
Employee DARREN BROWN with number A0001 was not found.

when field givename contains the value "DARREN", field surname contains the value "BROWN" and field empno contains the value "A0001"
Fields used in the Format Pattern must be used elsewhere in the RDML function.
Fields may be defined in the repository or internally within the function.
To include a colon (:) in the returned Formatted String, use two colons in the input Format pattern.
Example Format Pattern=
Employee no:::empno

Returned Formatted String=
Employee no:A0001
To include a character straight after the field, use brackets().
Example Format Pattern=
Employee no:::empno()NoSpace

Returned Formatted String=
Employee no:A0001NoSpace
Formatting option/s may be applied to a field value and specified in the Format Pattern.
Multiple options may be applied to a field value.
Formatting options must immediately follow the field name and be contained within brackets ().

Example Format Pattern=
Employee :givename(substr,1,1 UPPER). :SURNAME(trim upper)

Returned Formatted String=
Employee D. BROWN
When multiple formatting options are specified for a field value, the options are applied in the following order
1. edit code
2. substring
3. trim trailing (trim)
4. trim leading (triml)
5. trim all
6. lower
7. upper
The Edit code formatting option are applied only to numeric fields.
If an edit code formatting option is specified for a character field, it will be ignored.
Edit codes which suppress leading zeroes will remove any resulting leading blanks.

DBCS considerations

Text sections of the Format Pattern may contain DBCS or mixed characters. However the :field specification must be entered in single byte mode. Also any text section must be a complete string with the correct pairing of shift out/ shift in characters.

The substring format option is not DBCS sensitive by default. To enable DBCS, set the second optional argument to 'YES'. Note that the number for the start position and length are in character count, not in byte and the shift in and shift out bytes are not counted.

Example

This example retrieves information from a file and formats different lines into a standard browse list. A variety of formatting options are used to format field values.

     FUNCTION   OPTIONS(*DIRECT)                                        
     DEFINE     FIELD(#STRING) TYPE(*CHAR) LENGTH(75) COLHDG('Details') INPUT_ATR(LC)
     DEFINE     FIELD(#PATERN) TYPE(*CHAR) LENGTH(256) INPUT_ATR(LC)    
     DEF_LIST   NAME(#BRWLST) FIELDS((#STRING))                         
     **********                                                         
     SELECT     FIELDS((#EMPNO) (#GIVENAME) (#SURNAME) (#STARTDTE) (#TERMDATE) (#ADDRESS1) (#ADDRESS2) (#ADDRESS3) (#SALARY) (#POSTCODE)) FROM_FILE(PSLMST)
     CHANGE     FIELD(#PATERN) TO('''EMPLOYEE:: :empno :GIVENAME(substr,1,1 upper).:surname(upper trim)''')
     EXECUTE    SUBROUTINE(ADDTOBRW)                                    
     CHANGE     FIELD(#PATERN) TO('''          Start :startdte(editcode ,Y) Salary $:salary(editcode,J)''')
     EXECUTE    SUBROUTINE(ADDTOBRW)                                   
     CHANGE     FIELD(#PATERN) TO('''          Address:: :ADDRESS1(trim) :ADDRESS2(TRIM)''')
     EXECUTE    SUBROUTINE(ADDTOBRW)                                   
     CHANGE     FIELD(#PATERN) TO('''                   :aDDRESS3(trima ll) :postcode(editcode,4)''')
     EXECUTE    SUBROUTINE(ADDTOBRW)                                   
     ENDSELECT                                                         
     **********                                                        
     DISPLAY    BROWSELIST(#BRWLST)                                    
     RETURN                                                            
     ********** -------------------------------------------            
     SUBROUTINE NAME(ADDTOBRW)                                         
     USE        BUILTIN(FORMAT_STRING) WITH_ARGS(#PATERN) TO_GET(#STRING)
     ADD_ENTRY  #BRWLST                                                
     ENDROUTINE                                                         .

Content

Space Tools