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 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

• 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                                                         .