9.76 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

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

2

 

 

 

Technical Notes

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                                                         .